From 2f90f0eb3acc61383c798ae25e7a4c5f1bf70b09 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Tue, 10 Nov 2026 15:05:18 +0800 Subject: [PATCH] =?UTF-8?q?=E5=8F=A3=E5=BE=84=E5=8F=B0=E8=B4=A6=EF=BC=9A?= =?UTF-8?q?=E5=9B=BA=E5=AE=9A=E6=89=A7=E8=A1=8C=E3=80=81=E9=AA=8C=E8=AF=81?= =?UTF-8?q?=E5=AE=A1=E9=98=85=E5=8F=91=E5=B8=83=E4=B8=8E=E5=A2=9E=E9=87=8F?= =?UTF-8?q?=E9=87=8D=E5=AF=BC=E5=85=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - QueryCore 固定执行(K09):按已发布的不可变口径跑一次,交回类型化标量、发布/manifest 引用与逐查询证据 - 依赖闭包(K08):按选中的指标算出要拷的取数节点、要的入口字段,接进 derive / compose / metrics - SQL 模板参数完整性(K01):试跑、组合问数、派生图、运行时取数共用一套语义,缺参数在渲染前就拒 - 受限字段变更服务(K03)与口径领域边界(K01):改动打在整图深拷贝上,身份与证据归属不可改 - 版本化受控模板绑定(K04):业务口径按显式绑定落到 SQL,对不上就报 unsupported / needs_update - 验证记录(K05)与最小审阅:样例匹配不等于正式批准,审批人只从服务端身份取 - 发布依据清单(K07):发布时按不可变图物化内容寻址清单,正式用途按它判 - 增量重导入(K11)与 B/L/R 三方合并、受限自然语言修改提案(K12):只产候选,落图仍走既有写路径 - 接口与前端:口径草稿页接上字段变更、绑定状态、验证与重导入,新增 caliber-drafts / studio 检查脚本 验证:前端 tsc -b 通过。 --- backend/app/api/caliber_import.py | 343 +++ backend/app/api/copilot.py | 357 +++- backend/app/api/copilot_context.py | 49 +- backend/app/api/copilot_gen.py | 35 +- backend/app/api/evidence.py | 47 +- backend/app/api/ledger.py | 1296 +++++++++++- backend/app/api/runs.py | 271 ++- backend/app/api/workflows.py | 125 +- backend/app/apps/access.py | 114 +- backend/app/apps/publications.py | 1203 +++++++++++ backend/app/apps/resolve.py | 11 +- backend/app/apps/versions.py | 169 +- backend/app/auth/chat_policy.py | 115 +- backend/app/blueprints/publish_plan.py | 43 +- backend/app/capabilities/registry.py | 69 +- backend/app/chat/drive.py | 40 +- backend/app/chat/job.py | 17 +- backend/app/chat/launch.py | 66 +- backend/app/chat/turn.py | 29 +- backend/app/data/caliber_identity.py | 5 +- backend/app/db/base.py | 8 + backend/app/db/models.py | 266 +++ backend/app/engine/evidence.py | 36 +- backend/app/engine/evidence_reader.py | 48 +- backend/app/engine/launch.py | 46 +- backend/app/engine/nodes/llm.py | 138 +- backend/app/engine/nodes/merge.py | 26 +- backend/app/engine/nodes/metrics.py | 166 +- backend/app/engine/nodes/multi.py | 150 +- backend/app/engine/nodes/tools.py | 150 +- backend/app/engine/origin.py | 6 + backend/app/engine/runner.py | 181 +- backend/app/engine/schema.py | 24 +- backend/app/engine/variables.py | 21 +- backend/app/engine/verify_agent.py | 96 +- backend/app/ledger/authoring.py | 167 +- backend/app/ledger/bindings.py | 650 ++++++ backend/app/ledger/changes.py | 358 ++++ backend/app/ledger/closure.py | 631 ++++++ backend/app/ledger/compose.py | 214 +- backend/app/ledger/derive.py | 273 ++- backend/app/ledger/descriptor.py | 90 +- backend/app/ledger/docdraft.py | 115 +- backend/app/ledger/draftplan.py | 96 +- backend/app/ledger/fieldbaseline.py | 402 ++++ backend/app/ledger/issue.py | 58 +- backend/app/ledger/match.py | 23 +- backend/app/ledger/nlchange.py | 1015 +++++++++ backend/app/ledger/params.py | 669 ++++++ backend/app/ledger/querycore.py | 1721 +++++++++++++++ backend/app/ledger/recall.py | 47 +- backend/app/ledger/reconcile.py | 64 +- backend/app/ledger/reimport.py | 1323 ++++++++++++ backend/app/ledger/repository.py | 153 ++ backend/app/ledger/review.py | 148 ++ backend/app/ledger/validation.py | 595 ++++++ backend/app/ledger/view.py | 119 +- backend/app/look/calibers.py | 352 +++- backend/app/main.py | 10 +- backend/app/records/views.py | 16 + backend/app/tools/datasource.py | 20 +- backend/app/tools/registry.py | 31 + backend/tests/binding_samples.py | 257 +++ backend/tests/publication_samples.py | 174 ++ backend/tests/test_architecture_lifecycle.py | 7 +- backend/tests/test_blueprint_generation.py | 4 +- backend/tests/test_caliber_access.py | 313 +++ backend/tests/test_caliber_bindings.py | 754 +++++++ backend/tests/test_caliber_closure.py | 559 +++++ backend/tests/test_caliber_draft_reads.py | 338 +++ .../tests/test_caliber_entry_field_merge.py | 248 +++ backend/tests/test_caliber_field_baseline.py | 176 ++ backend/tests/test_caliber_field_changes.py | 673 ++++++ backend/tests/test_caliber_query_tool.py | 1487 +++++++++++++ backend/tests/test_caliber_regressions.py | 21 +- backend/tests/test_caliber_reimport.py | 848 ++++++++ backend/tests/test_caliber_selection.py | 329 +++ backend/tests/test_caliber_source_snapshot.py | 433 ++++ .../test_caliber_validation_real_chain.py | 199 ++ .../tests/test_caliber_validation_records.py | 771 +++++++ backend/tests/test_caliber_write_guard.py | 477 +++++ backend/tests/test_caliber_write_race.py | 176 ++ backend/tests/test_chat_turn_policy.py | 8 +- backend/tests/test_chat_user_caliber.py | 401 ++++ backend/tests/test_db_portable.py | 9 + backend/tests/test_evidence_duplicate_exec.py | 269 +++ backend/tests/test_inquiry_usage.py | 8 +- backend/tests/test_ledger_compose.py | 354 +++- backend/tests/test_ledger_derive.py | 171 +- backend/tests/test_ledger_descriptor.py | 120 +- backend/tests/test_ledger_docdraft_api.py | 47 +- backend/tests/test_ledger_issue.py | 127 +- backend/tests/test_ledger_nlchange.py | 1028 +++++++++ backend/tests/test_ledger_recall.py | 59 +- backend/tests/test_ledger_reconcile.py | 288 ++- backend/tests/test_ledger_trial.py | 100 + backend/tests/test_merge_node.py | 38 + backend/tests/test_metric_id_duplicate.py | 174 ++ backend/tests/test_publication_gate.py | 964 +++++++++ backend/tests/test_publication_manifest.py | 554 +++++ backend/tests/test_querycore_execute.py | 678 ++++++ backend/tests/test_querycore_perf.py | 588 ++++++ backend/tests/test_querycore_user_access.py | 1125 ++++++++++ backend/tests/test_run_timing.py | 11 +- backend/tests/test_runs_cancel_waiting.py | 2 +- backend/tests/test_sql_parameter_integrity.py | 633 ++++++ backend/tests/test_tool_evidence.py | 4 +- backend/tests/test_variables.py | 80 + backend/tests/test_verify_agent.py | 95 + frontend/src/api/caliberLedger.ts | 106 +- frontend/src/api/client.ts | 5 +- frontend/src/lib/terms.ts | 18 + frontend/src/lib/termsLedger.ts | 353 ++++ frontend/src/pages/StudioPage.tsx | 67 +- frontend/src/pages/ledger/CaliberDrafts.tsx | 1848 +++++++++++++++- frontend/src/run/LedgerReconcile.tsx | 2 + frontend/src/run/LedgerStep.tsx | 18 +- frontend/src/run/LedgerTurn.tsx | 23 +- frontend/src/store/studio.ts | 78 +- frontend/src/typesBlueprint.ts | 7 +- frontend/src/typesLedger.ts | 466 +++- scripts/check-all.mjs | 8 + scripts/check-caliber-drafts.mjs | 1869 +++++++++++++++++ scripts/check-ledger.mjs | 39 +- scripts/check-studio.mjs | 85 + scripts/ledger-fixtures.mjs | 18 +- 126 files changed, 35506 insertions(+), 809 deletions(-) create mode 100644 backend/app/api/caliber_import.py create mode 100644 backend/app/apps/publications.py create mode 100644 backend/app/ledger/bindings.py create mode 100644 backend/app/ledger/changes.py create mode 100644 backend/app/ledger/closure.py create mode 100644 backend/app/ledger/fieldbaseline.py create mode 100644 backend/app/ledger/nlchange.py create mode 100644 backend/app/ledger/params.py create mode 100644 backend/app/ledger/querycore.py create mode 100644 backend/app/ledger/reimport.py create mode 100644 backend/app/ledger/repository.py create mode 100644 backend/app/ledger/review.py create mode 100644 backend/app/ledger/validation.py create mode 100644 backend/tests/binding_samples.py create mode 100644 backend/tests/publication_samples.py create mode 100644 backend/tests/test_caliber_access.py create mode 100644 backend/tests/test_caliber_bindings.py create mode 100644 backend/tests/test_caliber_closure.py create mode 100644 backend/tests/test_caliber_draft_reads.py create mode 100644 backend/tests/test_caliber_entry_field_merge.py create mode 100644 backend/tests/test_caliber_field_baseline.py create mode 100644 backend/tests/test_caliber_field_changes.py create mode 100644 backend/tests/test_caliber_query_tool.py create mode 100644 backend/tests/test_caliber_reimport.py create mode 100644 backend/tests/test_caliber_selection.py create mode 100644 backend/tests/test_caliber_source_snapshot.py create mode 100644 backend/tests/test_caliber_validation_real_chain.py create mode 100644 backend/tests/test_caliber_validation_records.py create mode 100644 backend/tests/test_caliber_write_guard.py create mode 100644 backend/tests/test_caliber_write_race.py create mode 100644 backend/tests/test_chat_user_caliber.py create mode 100644 backend/tests/test_evidence_duplicate_exec.py create mode 100644 backend/tests/test_ledger_nlchange.py create mode 100644 backend/tests/test_metric_id_duplicate.py create mode 100644 backend/tests/test_publication_gate.py create mode 100644 backend/tests/test_publication_manifest.py create mode 100644 backend/tests/test_querycore_execute.py create mode 100644 backend/tests/test_querycore_perf.py create mode 100644 backend/tests/test_querycore_user_access.py create mode 100644 backend/tests/test_sql_parameter_integrity.py create mode 100644 scripts/check-caliber-drafts.mjs diff --git a/backend/app/api/caliber_import.py b/backend/app/api/caliber_import.py new file mode 100644 index 00000000..f4b09c74 --- /dev/null +++ b/backend/app/api/caliber_import.py @@ -0,0 +1,343 @@ +"""增量重导入的接口(K11):建一次导入、看工作项和冲突、接受选定字段、拒绝、人工对齐、显式恢复。 + +**认证主体只从服务端身份取。** 发起人、接受人一律 `current_principal()`(开登录时是认证用户名,关登录时是自报署名); +请求体里写 actor 一概不看。这几个接口不登记进 `auth/keys.KEY_ROUTES`(访问密钥不开放绕过),路由挂在搭建者那一道门上 +(main.py 的 `_BUILDER`,和 /api/ledger 下其余写接口一致)。 + +**R 只是候选,不改 L。** 建一次导入只在后台抽候选、算逐字段三方;真正落到图上的是「接受选定字段」——它走现有版本 / +CAS / 操作语义(另见 app/ledger/reimport.py 的 accept_fields),并按被接受的那几格推进字段基线 B。冲突没被接受之前, +L 和 B 一个字节都不动。 + +接口形状: +- POST /api/ledger/drafts/{draft_id}/imports 建一次导入(可带 request_id 幂等),后台抽候选 +- GET /api/ledger/drafts/{draft_id}/imports 这次草稿的导入列表 +- GET /api/ledger/imports/{run_id} 一次导入的工作项(含逐字段三方、逐格 acceptable、align_key)、冲突 +- POST /api/ledger/imports/{run_id}/items/{item_id}/align 人工把一条工作项对到图上某条指标 +- POST /api/ledger/imports/{run_id}/accept 接受选定字段(定位按 item_id;落到 L + 按字段推进 B,原子) +- POST /api/ledger/imports/{run_id}/reject 拒绝选定字段 / 整条(保持 L 不动) +- POST /api/ledger/imports/{run_id}/refresh 按现在的 L / B 重算三方(import_stale_l 之后的恢复动作) +- POST /api/ledger/imports/{run_id}/resume 显式恢复未完成的工作项(按持久对齐键认项,不按位置) +""" +from __future__ import annotations + +from typing import Any + +from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException +from pydantic import BaseModel, ConfigDict, Field +from sqlalchemy import select +from sqlalchemy.exc import IntegrityError +from sqlalchemy.ext.asyncio import AsyncSession + +from app.api.coded import CodedHTTPException +from app.db.base import get_session +from app.db.models import CaliberDraft, CaliberImportItem, CaliberImportRun, Workflow +from app.ledger import fieldbaseline, reimport + +router = APIRouter(prefix="/api/ledger", tags=["ledger"]) + +#: 接口自己的机器码(reimport 里的那几个之外) +IMPORT_DRAFT_UNAVAILABLE = "import_draft_unavailable" +IMPORT_CARD_GONE = "card_not_found" + + +def _refused(exc: reimport.ImportRefused) -> CodedHTTPException: + return CodedHTTPException(exc.status_code, exc.message, exc.code, extra=exc.extra or None) + + +async def _draft_or_404(session: AsyncSession, draft_id: str) -> CaliberDraft: + draft = await session.get(CaliberDraft, draft_id) + if draft is None: + raise HTTPException(404, "口径草稿不存在,可能已被删除") + return draft + + +async def _run_or_404(session: AsyncSession, run_id: str) -> CaliberImportRun: + run = await session.get(CaliberImportRun, run_id) + if run is None: + raise HTTPException(404, "这次导入不存在,可能已被删除") + return run + + +async def _items(session: AsyncSession, run_id: str) -> list[CaliberImportItem]: + return list((await session.execute(select(CaliberImportItem).where(CaliberImportItem.run_id == run_id) + .order_by(CaliberImportItem.seq))).scalars()) + + +async def _write_target(session: AsyncSession, run: CaliberImportRun) -> tuple[CaliberDraft, Workflow, str]: + """这次导入要落到的(草稿、工作流、口径卡):卡必须是可写的源头口径卡,认不出就拒。""" + from app.api.ledger import draft_card + + draft = await _draft_or_404(session, run.draft_id) + workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None + if workflow is None or not workflow.graph: + raise CodedHTTPException(409, "这份草稿还没接管到工作流上(没有可改的图):导入落不到图上,请先起草或接上一次运行", + IMPORT_DRAFT_UNAVAILABLE) + card_id, _cards = draft_card(workflow.graph) + if not card_id: + raise CodedHTTPException(409, "当前画布认不出唯一的口径卡:请在目标卡上明确要改哪一张", IMPORT_CARD_GONE) + return draft, workflow, str(card_id) + + +def _field_view(path: str, cell: Any) -> dict[str, Any]: + cell = cell if isinstance(cell, dict) else {} + state = str(cell.get("state") or "missing") + acceptable = bool(cell.get("acceptable")) if "acceptable" in cell else state in reimport.ACCEPT_STATES + return {"path": path, "state": state, "b": cell.get("b"), "l": cell.get("l"), "r": cell.get("r"), + "b_present": bool(cell.get("b_present")), "l_present": bool(cell.get("l_present")), + "r_present": bool(cell.get("r_present")), "decided": cell.get("decided"), + "acceptable": acceptable} + + +def _item_view(item: CaliberImportItem) -> dict[str, Any]: + fields = item.fields if isinstance(item.fields, dict) else {} + order = list(fieldbaseline.field_paths()) + ordered = [path for path in order if path in fields] + [path for path in fields if path not in order] + failed = item.status == "failed" + return { + "item_id": item.id, "seq": item.seq, "metric_id": item.metric_id or "", + "candidate_id": item.candidate_id or "", "align_key": item.align_key or "", + "name": item.name or "", "status": item.status, "align": dict(item.align or {}), + "error": item.error or "", "failed": failed, + "accepted": list(item.accepted or []), "rejected": list(item.rejected or []), + "applied_revision": item.applied_revision, + "fields": [_field_view(path, fields.get(path)) for path in ordered], + } + + +def _run_view(run: CaliberImportRun, items: list[CaliberImportItem]) -> dict[str, Any]: + views = [_item_view(item) for item in items] + conflicts: list[dict[str, Any]] = [] + for view in views: + for cell in view["fields"]: + if cell["state"] in ("conflict", "manual", "missing"): + conflicts.append({"metric_id": view["metric_id"], "item_id": view["item_id"], + "seq": view["seq"], "name": view["name"], + "path": cell["path"], "state": cell["state"], + "b": cell["b"], "l": cell["l"], "r": cell["r"]}) + return { + "run_id": run.id, "draft_id": run.draft_id, "workflow_id": run.workflow_id or "", "status": run.status, + "error": run.error or "", "actor": run.actor or "", "request_id": run.request_id or "", + "source_snapshot": dict(run.source_snapshot or {}), "visible_chunk_ids": list(run.visible_chunk_ids or []), + "prompt_version": run.prompt_version, "parse_version": run.parse_version, "model_id": run.model_id or "", + "items_total": run.items_total, "items_decided": run.items_decided, + "created_at": run.created_at.isoformat() if run.created_at else "", + "items": views, "conflicts": conflicts, + } + + +class ImportCreateIn(BaseModel): + model_config = ConfigDict(extra="forbid") + + #: 客户端幂等键:同一份草稿 + 同一个 request_id 只建一次 run(重放交回上一次那一次) + request_id: str | None = Field(default=None, max_length=64) + + +class ImportAcceptItemIn(BaseModel): + model_config = ConfigDict(extra="forbid") + + #: 首选:工作项的稳定主键。旧调用只给 metric_id 时要求它在这条导入里唯一对得上一条工作项 + item_id: str | None = Field(default=None, max_length=32) + metric_id: str | None = Field(default=None, max_length=64) + #: 要接受的字段路径;auto=true 时不用给(**只**收还没决定的「无冲突更新 + 新增候选」) + fields: list[str] = Field(default_factory=list) + auto: bool = False + + +class ImportAcceptIn(BaseModel): + model_config = ConfigDict(extra="forbid") + + items: list[ImportAcceptItemIn] = Field(min_length=1) + expected_revision: int | None = None + request_id: str | None = Field(default=None, max_length=64) + + +class ImportRejectItemIn(BaseModel): + model_config = ConfigDict(extra="forbid") + + item_id: str | None = Field(default=None, max_length=32) + metric_id: str | None = Field(default=None, max_length=64) + seq: int | None = None + #: 空 = 整条拒绝(还没决定的格子都拒);没对齐上的工作项优先按 item_id 指 + fields: list[str] = Field(default_factory=list) + + +class ImportRejectIn(BaseModel): + model_config = ConfigDict(extra="forbid") + + items: list[ImportRejectItemIn] = Field(min_length=1) + note: str | None = Field(default=None, max_length=500) + + +class ImportAlignIn(BaseModel): + model_config = ConfigDict(extra="forbid") + + #: 对齐到图上哪条指标;空串 = 取消对齐(当作新指标) + metric_id: str = Field(default="", max_length=64) + + +@router.post("/drafts/{draft_id}/imports", status_code=201) +async def create_import(draft_id: str, payload: ImportCreateIn, background: BackgroundTasks, + session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """建一次增量导入:后台按这份草稿的来源文档重新抽候选 R,和当前图 L、字段基线 B 逐字段比对。不改 L、不改 B。 + + 带 request_id 的:同一份草稿 + 同一个 request_id 已经建过就交回那一次(200 的语义,仍回 201 由前端按 run_id 认), + 不重复抽、不重复建工作项。 + """ + from app.api.deps import current_principal, ensure_role + + ensure_role("builder") + actor = current_principal().username or "" + draft = await _draft_or_404(session, draft_id) + existing = await _by_request_id(session, draft_id, payload.request_id) + if existing is not None: + return _run_view(existing, await _items(session, existing.id)) + run = CaliberImportRun(draft_id=draft.id, workflow_id=draft.workflow_id, status="queued", actor=actor, + request_id=payload.request_id or None, checkpoint={"stage": "queued"}) + session.add(run) + try: + await session.flush() + await session.commit() + except IntegrityError: + # 两路真并发带同一个 request_id:后到的那一路撞唯一键,重查一次交回赢的那一次(不重复抽、不重复建工作项) + await session.rollback() + existing = await _by_request_id(session, draft_id, payload.request_id) + if existing is None: + raise + return _run_view(existing, await _items(session, existing.id)) + background.add_task(reimport.start, run.id) + return _run_view(run, []) + + +async def _by_request_id(session: AsyncSession, draft_id: str, request_id: str | None) -> CaliberImportRun | None: + if not request_id: + return None + return (await session.execute(select(CaliberImportRun).where( + CaliberImportRun.draft_id == draft_id, CaliberImportRun.request_id == request_id, + CaliberImportRun.status != "cancelled").order_by(CaliberImportRun.created_at.desc()))).scalars().first() + + +@router.get("/drafts/{draft_id}/imports") +async def list_imports(draft_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + from app.api.deps import ensure_role + + ensure_role("builder") + await _draft_or_404(session, draft_id) + rows = (await session.execute(select(CaliberImportRun).where(CaliberImportRun.draft_id == draft_id) + .order_by(CaliberImportRun.created_at.desc()))).scalars() + return {"runs": [_run_view(run, await _items(session, run.id)) for run in rows]} + + +@router.get("/imports/{run_id}") +async def get_import(run_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + from app.api.deps import ensure_role + + ensure_role("builder") + run = await _run_or_404(session, run_id) + return _run_view(run, await _items(session, run_id)) + + +@router.post("/imports/{run_id}/items/{item_id}/align") +async def align_import_item(run_id: str, item_id: str, payload: ImportAlignIn, + session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """人工把一条工作项对到图上某条指标上(或取消对齐)。「baseline_unknown 必须人工对齐」和「同名不同范围」都走这里。 + + 重新对齐会清掉旧的决定(换了对哪一条,决定就换了对象),只重算三方、不改 L、不改 B。 + """ + from app.api.deps import ensure_role + + ensure_role("builder") + run = await _run_or_404(session, run_id) + item = await session.get(CaliberImportItem, item_id) + if item is None or item.run_id != run.id: + raise CodedHTTPException(404, "这条工作项不存在", reimport.IMPORT_ITEM_UNKNOWN) + draft, workflow, _card_id = await _write_target(session, run) + try: + await reimport.realign_item(session, run=run, draft=draft, workflow=workflow, item=item, + metric_id=payload.metric_id) + except reimport.ImportRefused as exc: + raise _refused(exc) from None + return _run_view(run, await _items(session, run.id)) + + +@router.post("/imports/{run_id}/accept") +async def accept_import(run_id: str, payload: ImportAcceptIn, + session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """接受选定字段:**一次性**落到 L(新增一版图),并按被接受的那几格推进 B。 + + 原子性:先把推进后的不可变 B 工件写出来(写不出来就整次失败,L 不落;失败可能留下没人引用的孤儿工件), + 再在**同一个数据库事务**里提交 L 的新版本、工作项的决定、草稿上的新 B 引用与历史。任一步失败一起回滚, + 新 L 不可见;不会出现「L 提交了、B 永远没推进」的空档。 + + 并发与幂等:expected_revision 是读到的 Workflow.version(对不上回 409 stale_revision);带 request_id 的按 + (主体 + 工作流 + 卡 + request_id)认这一次,重放交回已提交的结果(B 读得回来),同键不同内容回 409 + idempotency_conflict。 + """ + from app.api.deps import current_principal, ensure_role + + ensure_role("builder") + actor = current_principal().username or "" + run = await _run_or_404(session, run_id) + draft, workflow, card_id = await _write_target(session, run) + try: + result = await reimport.accept_fields( + session, run=run, draft=draft, workflow=workflow, card_id=card_id, + selections=[spec.model_dump() for spec in payload.items], actor=actor, + request_id=payload.request_id, expected_revision=payload.expected_revision) + except reimport.ImportRefused as exc: + raise _refused(exc) from None + view = _run_view(run, await _items(session, run.id)) + return {**view, **result} + + +@router.post("/imports/{run_id}/reject") +async def reject_import(run_id: str, payload: ImportRejectIn, + session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """拒绝选定字段 / 整条工作项:保持 L 不动,也不推进 B。""" + from app.api.deps import ensure_role + + ensure_role("builder") + run = await _run_or_404(session, run_id) + try: + await reimport.reject_fields(session, run=run, + selections=[spec.model_dump(exclude_unset=True) for spec in payload.items], + note=payload.note) + except reimport.ImportRefused as exc: + raise _refused(exc) from None + return _run_view(run, await _items(session, run.id)) + + +@router.post("/imports/{run_id}/refresh") +async def refresh_import(run_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """按**现在的** L / B 重算这次导入还没决定的三方,并刷新每项的比较锚点。 + + 这是 409 `import_stale_l` 之后的恢复动作:L 在候选之后被人改过(或另一次接受动过),三方要按现在的口径重算, + 人看过新的三方再确认、再接受。工作项、人的决定、每项自己的来源依据都不动。 + """ + from app.api.deps import ensure_role + + ensure_role("builder") + run = await _run_or_404(session, run_id) + draft, workflow, _card_id = await _write_target(session, run) + await reimport.refresh(session, run=run, draft=draft, workflow=workflow) + return _run_view(run, await _items(session, run.id)) + + +@router.post("/imports/{run_id}/resume") +async def resume_import(run_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """显式恢复:把这次导入重新排进后台,续做还没完成的工作项。已接受 / 拒绝的不动,不重复建版。 + + 工作项按持久对齐键认(稳定 metric 身份 + 来源证据),顺序 / 条数变了也不串项。真正的排队在 reimport.resume 里 + (它改状态、再排进后台);这次响应是「已排队」的确认,接着轮询详情看结果。""" + from app.api.deps import ensure_role + + ensure_role("builder") + run = await _run_or_404(session, run_id) + try: + await reimport.resume(session, run) + except reimport.ImportRefused as exc: + raise _refused(exc) from None + await session.refresh(run) + return _run_view(run, await _items(session, run.id)) + + +__all__ = ["router"] diff --git a/backend/app/api/copilot.py b/backend/app/api/copilot.py index 12fa575b..63b2b5ea 100644 --- a/backend/app/api/copilot.py +++ b/backend/app/api/copilot.py @@ -2,11 +2,13 @@ from __future__ import annotations import asyncio import copy +import inspect import json import logging import math import re import time +from collections.abc import Mapping from dataclasses import dataclass from typing import Any, Literal @@ -114,14 +116,19 @@ def _tool_catalog(rows: list[Any], *, builtins: frozenset[str] | None = None, an async def _look_service(session: AsyncSession, payload: GenerateIn, sources: list[Any], *, graph: dict[str, Any] | None, kinds: tuple[str, ...] = ("table", "capability"), - catalog_view: Any = None) -> Any: + catalog_view: Any = None, caliber: str = copilot_context.CALIBER_LOOK, + actor: Any = None) -> Any: """这一轮的查看服务(copilot_context.look_service)。挑选模型用同一个助手模型,第一次要挑时才拿。catalog_view:表详情 - 里给哪一份数据目录(data/catalog_view.py),不给是当前目录。""" + 里给哪一份数据目录(data/catalog_view.py),不给是当前目录。 + + caliber 是这一轮口径这一档怎么用(copilot_context.CALIBER_*):问数据里搭建者及以上是 compose(look 之后 use_caliber)、 + 普通使用者是 query(look 之后让 agent 调口径查询工具,K14)。actor 是这次是谁:口径清单按资产授权收窄(普通使用者只看 + 得到有授权的版本)。""" spec = await copilot_model_spec(session, payload, max_tokens=copilot_context.PICK_MAX_TOKENS) return await copilot_context.look_service(sources, spec=spec, graph=graph, kinds=kinds, answer=payload.intent == "answer", catalog_view=catalog_view, trail={"conversation_id": getattr(payload, "conversation_id", None)}, - session=session) + session=session, actor=actor, caliber=caliber) NODE_REFERENCE = """\ @@ -445,9 +452,15 @@ class GenerateIn(BaseModel): conversation_id: str | None = None #: 这一轮只查这几个数据源(id 或名字)。不传或空表示不限 datasource_ids: list[str] | None = None + #: 这一轮在对话里是哪一轮(问数据那一轮:conversations.ConversationTurn.id)。固定执行起的那次运行要用它记来源 + #: (和问数据自己发起的运行记同一份:chat/job.ChatDriver.generate_in);画布、评测没有这一项 + turn_id: str | None = None #: 问数据里用户原本问的那句话。自动重来、重试本轮时 instruction 是带着原因的那段话(「上一次运行没有成功:…」), #: 自查按问题判分析意图(app/analysis/intent)时用这一句;不传就用 instruction question: str | None = None + #: Ask Data 的固定请求(K12,app/ledger/nlchange.py):已经明确 workflow/card/metric_ids/inputs 的请求直接进 + #: QueryCore,不经模型的解析/规划;没匹配口径就进探索、含糊业务条件先澄清,不静默换计算规则。不传就是原来的问数据路径 + fixed_request: dict[str, Any] | None = None def _question_of(payload: GenerateIn) -> str | None: @@ -971,8 +984,11 @@ _CHAT_USER_PROMPT = ( "2. tool 节点和 agent 都只能用 db_query__<数据源>、db_schema__<数据源> 和上面列出的内置工具:取数用 tool 节点" "(tool 写 db_query__<数据源>,args.sql 写好 SQL)或 agent(tools 里绑定这两种数据源工具)。不要用 http_request、" "records_append 这类写入或连外部的工具,工具名不要用 {{ }} 拼\n" - "3. 查询一律只读,不要写改数据的 SQL\n" - "4. 任何节点、图级 defaults、tool 节点的 args 里都不要写 memory_scope、collection:记忆范围和知识库由平台定" + "3. 上面工具清单里有 caliber_query(口径查询):用户问的数只要在已发布口径里对得上,就照 look 交回的「取数写法」调它" + "取数(在 agent 的 prompt 里写清要调它、参数照抄),交回的指标值写进报告。**不要**自己拿 db_query__ 拼一份差不多的 SQL," + "口径的 SQL 你也看不到、不要照着抄;没有对得上的口径时才自己查表\n" + "4. 查询一律只读,不要写改数据的 SQL\n" + "5. 任何节点、图级 defaults、tool 节点的 args 里都不要写 memory_scope、collection:记忆范围和知识库由平台定" ) @@ -1870,6 +1886,291 @@ async def generate_stream(payload: GenerateIn): ) +#: 这次执行走的是哪条路(final / error 的 execution.via) +FIXED_VIA = "querycore" +#: 这一次跑完了、但没算成(遮罩、空值、部分结果、超时)时给普通 user 的机器码 +RESULT_FAILED = "caliber_result_failed" +#: 普通 user 看到的安全白话:内部的失败原话可能带着卡 id / 版本号 / 工作流引用与查询细节,不原样外发 +USER_FAILED = "这次没能按这份固定口径算出可用的数:可以换一种问法,或让搭建者检查这份口径是不是能用了" +#: 普通 user 看得到的指标字段(id、质量检查、参数、查询引用这些内部材料一律不给) +_USER_METRIC_KEYS = ("name", "value", "value_type", "rendered", "unit", "status", "masked", "decimals", "format") +#: 结果摊平时认的属性名(两种实现交回的对象都按这一份读,见 _outcome_data) +_OUTCOME_KEYS = ("run_id", "status", "ok", "workflow_id", "card_id", "version", "purpose", "publication", + "selection", "parameters", "metrics", "queries", "data", "quality", "problems") + + +def _outcome_data(outcome: Any) -> dict[str, Any]: + """这次固定执行的结果摊平成一份字典:两条路(搭建者的进程内固定执行、普通 user 的父图口径工具那条路)都认。""" + made = getattr(outcome, "as_dict", None) + if callable(made): + return dict(made()) + if isinstance(outcome, Mapping): + return dict(outcome) + return {key: value for key in _OUTCOME_KEYS if (value := getattr(outcome, key, None)) is not None} + + +def _user_metrics(data: Mapping[str, Any]) -> list[dict[str, Any]]: + """普通 user 看到的指标值:只留业务上的名字与值,不留 id 与内部材料。""" + out: list[dict[str, Any]] = [] + for metric in data.get("metrics") or (): + if isinstance(metric, Mapping): + out.append({key: metric[key] for key in _USER_METRIC_KEYS if metric.get(key) is not None}) + return out + + +def _user_execution(data: Mapping[str, Any]) -> dict[str, Any]: + """普通 user 看得到的那一段回执:via / run_id / status 与必要指标值。 + + 没有卡 id、工作流 id、版本号、发布清单、选择、表、参数与查询引用(「不要让用户看到内部 ID」)。""" + made: dict[str, Any] = {"via": FIXED_VIA} + for key in ("run_id", "status"): + if data.get(key) is not None: + made[key] = data[key] + metrics = _user_metrics(data) + if metrics: + made["metrics"] = metrics + return made + + +def _as_text(value: Any) -> str: + return "" if value is None else str(value) + + +def _user_error(message: str, code: str, data: Mapping[str, Any] | None = None) -> dict[str, Any]: + """普通 user 的失败结局:一句安全白话 + via / run_id / status + 已经拿到的指标值,不带任何内部引用。""" + failed = {"op": "error", "message": message, "code": code, "reason": message} + if data: + failed["execution"] = _user_execution(data) + return failed + + +def _terminal(failed: dict[str, Any]) -> list[dict[str, Any]]: + """终止型结局:error(必要时带 execution)+ next。命中了但没授权、或者命中了执行失败,都走这里——不换路、不重来。""" + from app.chat import turn + + return [{**failed, "next": turn.next_step(failed)}] + + +def _not_permitted_ops(code: str) -> list[dict[str, Any]]: + """命中但没授权:终止型结局(error + next=fail),照实说没有授权,**不回退旧的 Agent 路径**。 + + 说法和 `nlchange.auto_route` 的拒绝同一条(nlchange.NOT_PERMITTED):两个字面出口共用一句,不出现任何内部引用。""" + from app.ledger import nlchange + + return _terminal(_user_error(nlchange.NOT_PERMITTED, code)) + + +def _failed_ops(code: str, *, detail: str, ordinary: bool, data: Mapping[str, Any] | None = None) -> list[dict[str, Any]]: + """命中之后的失败(清单、参数、绑定、超时……):终止型结局。 + + 搭建者及以上照实给内部原话(detail);普通 user 只给安全白话——detail 里可能带着卡 id、版本号、工作流引用与查询 + 细节,一概不外发(投影点在这里)。""" + if ordinary: + return _terminal(_user_error(USER_FAILED, code, data)) + return _terminal({"op": "error", "message": detail, "code": code, "reason": detail}) + + +def _builder_final(payload: GenerateIn, data: Mapping[str, Any]) -> dict[str, Any]: + """搭建者及以上看到的那条 final:全部依据(via / workflow / card / version / manifest / selection 引用)。""" + graph = payload.base_graph or {"nodes": [], "edges": []} + values = "、".join(f"{m.get('name') or m.get('id')} {_as_text(m.get('rendered'))}".strip() + for m in data.get("metrics") or ()) + return {"op": "final", "graph": graph, "issues": [], "autorun": False, "layout": {}, + "explanation": f"QueryCore 按固定口径(v{data.get('version')})算好了" + (f":{values}" if values else ""), + "run_id": data.get("run_id"), + "execution": {"via": FIXED_VIA, "run_id": data.get("run_id"), "ok": data.get("ok"), + "status": data.get("status"), "workflow_id": data.get("workflow_id"), + "card_id": data.get("card_id"), "version": data.get("version"), + "metrics": [dict(m) for m in data.get("metrics") or ()], + "problems": [dict(p) for p in data.get("problems") or ()], + "publication": dict(data.get("publication") or {}), + "selection": dict(data.get("selection") or {})}} + + +def _user_final(payload: GenerateIn, data: Mapping[str, Any]) -> dict[str, Any]: + """普通 user 看到的那条 final:安全白话 + via / run_id / status + 必要指标值。 + + 这是投影点:口径身份(工作流 / 卡 / 版本)、发布清单与选择、表、参数、查询与哈希一概不出这个门——使用者看到的数是 + 「按这份口径算出来的」,不是「哪一版哪张卡哪条 SQL」(遮罩由执行那条路在工具边界保证)。""" + metrics = _user_metrics(data) + values = "、".join(text for text in ( + f"{m.get('name') or ''} {_as_text(m.get('rendered') if m.get('rendered') is not None else m.get('value'))}" + .strip() for m in metrics) if text) + final = {"op": "final", "graph": payload.base_graph or {"nodes": [], "edges": []}, "issues": [], + "autorun": False, "layout": {}, + "explanation": "按这份固定口径算好了" + (f":{values}" if values else ""), + "execution": _user_execution(data)} + if data.get("run_id") is not None: + final["run_id"] = data["run_id"] + return final + + +def _querycore_final(payload: GenerateIn, outcome: Any) -> dict[str, Any]: + """按固定口径算成之后的那条 final——固定请求接缝与自动路由**共用同一形状**(前端不必为多一条路改)。 + + 搭建者及以上照旧清楚标出这是 QueryCore 的固定执行(via / workflow / card / version / manifest / selection 引用)和 + 这次的 run_id;普通 user 只给安全白话与 via / run_id / status / 必要指标值(见 _user_final)。autorun=false(运行 + 已经发生)。""" + from app.api.deps import restricted + from app.chat import turn + + data = _outcome_data(outcome) + final = _user_final(payload, data) if restricted() else _builder_final(payload, data) + final["next"] = turn.next_step(final) + return final + + +def _caller() -> tuple[Any, str | None]: + """这次请求的人:完整身份 + 主体名(关登录时是自报署名,可能为空)。""" + from app.api.deps import current_principal + + principal = current_principal() + return principal, (principal.username or None) + + +async def _allowed_calibers(session: AsyncSession, principal: Any) -> Any: + """这个人按**资产授权**能用的口径版本:{(工作流, 版本): 角色};搭建者及以上不限(None)。 + + 普通 user 只看「授权给它的应用当前版本钉住的那些口径版本」(app/apps/access.usable_calibers:AppGrant 的 use 及以上 + 加上当前 AppVersion.pins)。builder / admin / 关登录由调用方**显式放行**:它们本来就能直接按口径执行,不按资产授权 + 收窄,也不把它们的角色写进那个只认授权的函数里。""" + from app.api.deps import restricted + from app.apps import access + + if not restricted(): + return None + return await access.usable_calibers(session, principal) + + +def _run_origin(payload: GenerateIn) -> dict[str, Any]: + """这条固定执行起的那次运行记在**哪一轮问数据**上(execute_prepared 的 origin):对话 + 这一轮,和问数据自己发起的 + 运行记同一份(chat/job.ChatDriver.launch_args)。 + + 运行靠它回溯到哪一轮(ledger/issue._conversation_of 取出具来源、证据与页面重载按它认「这次运行是哪一轮的」); + 没有对话时(画布上直接调、评测)不留空键,origin_kind 那一项照样是 chat(这次是问数据来源)。""" + origin = {"conversation_id": payload.conversation_id, "turn_id": payload.turn_id} + return {key: value for key, value in origin.items() if value} + + +async def _prepared_execute(session: AsyncSession, *, request: Mapping[str, Any], purpose: str, + actor: str | None, origin: Mapping[str, Any] | None = None) -> Any: + """普通 user 的执行:走 prepare 好的父图 + 真实 `caliber_query` 工具那条路(`querycore.execute_prepared`)。 + + 遮罩与只读由那条路保证(父图按使用者的那一档发起,同他自己发起的问数据运行):这里把这次的口径身份、指标与入口取值, + **当前认证主体**(记进运行来源,遮罩按它判)与**这次是哪段对话的哪一轮**(origin,见 `_run_origin`)交过去——那次运行 + 因此归属这一轮、能重载查看,不是一条来路不明的运行。purpose 是宿主常量那一档(普通问数 = compose,不要求正式验证 + 审阅)。按它的形参表筛一遍再调:那一边不收的键(比如 purpose,那条路自己固定成 compose)不塞进去——**只筛一次, + 不重试**:重试等于再发一次运行。""" + from app.ledger import querycore + + given: dict[str, Any] = {"workflow_id": request.get("workflow_id"), "card_id": request.get("card_id"), + "metric_ids": list(request.get("metric_ids") or []), + "inputs": dict(request.get("inputs") or {}), "version": request.get("version"), + "purpose": purpose, "actor": actor, "origin_kind": "chat", + "origin": dict(origin or {})} + parameters = inspect.signature(querycore.execute_prepared).parameters + if not any(item.kind == item.VAR_KEYWORD for item in parameters.values()): + given = {key: value for key, value in given.items() if key in parameters} + if not given.get("origin"): + given.pop("origin", None) # 那一边不收空 origin(没有对话时不留一个空壳来源) + return await querycore.execute_prepared(session, **given) + + +async def _execute_route(session: AsyncSession, *, request: Mapping[str, Any], purpose: str, actor: str | None, + prepared: bool, payload: GenerateIn) -> Any: + """按一条已经定下来的固定请求执行:普通 user 走父图 + 真实 caliber_query 工具那条路,搭建者及以上直接固定执行。""" + if prepared: + return await _prepared_execute(session, request=request, purpose=purpose, actor=actor, + origin=_run_origin(payload)) + from app.ledger import querycore + + return await querycore.execute(session, purpose=purpose, **request) + + +async def _fixed_request_ops(payload: GenerateIn): + """K12 的固定请求路由接缝(Ask Data):确定请求**直接按固定口径执行**(内部 LLM 仍为 0),不经模型的解析/规划。 + + 含糊业务条件先澄清(reply)、没有匹配口径就进探索(reply),绝不静默换计算规则;能确定的直接按固定口径执行一次, + 交一条 final(autorun=false,运行已经发生)。普通 user 走**同一道授权闸**(app/apps/access.caliber_role:授权给它的 + 应用当前版本钉住的那些口径版本)与同一条执行路:没授权、或者执行失败(清单/参数/绑定/超时)都照实回一条终止型 + 结局(error + next=fail),**不降级成 Agent 路径**,也不绕过遮罩;数和说法只给安全白话。这一段不取助手模型、不读 + 目录、不拼历史——路由本身零模型。""" + from app.api.deps import restricted + from app.apps import access + from app.db.base import SessionLocal + from app.ledger import nlchange, querycore + + ordinary = restricted() + principal, actor = _caller() + async with SessionLocal() as session: + routed = await nlchange.route(session, request=payload.fixed_request or {}) + if routed.mode != nlchange.ROUTE_EXECUTE: + lines = [routed.reason] + lines += [item.question for item in routed.clarifications] + yield {"op": "reply", "text": "\n".join(line for line in lines if line)} + return + if ordinary: + # 和自动路由同一道闸:授权范围里没有这一版就到此为止,既不执行也不换路 + role = await access.caliber_role(session, principal, str(routed.request.get("workflow_id") or ""), + int(routed.request.get("version") or 0)) + if not access.at_least(role, "use"): + for op in _not_permitted_ops(nlchange.ROUTE_NOT_PERMITTED): + yield op + return + request = {key: value for key, value in routed.request.items() if key != "purpose"} + purpose = str(routed.request.get("purpose") or querycore.DEFAULT_PURPOSE) + try: + outcome = await _execute_route(session, request=request, purpose=purpose, actor=actor, prepared=ordinary, + payload=payload) + except querycore.QueryCoreRefused as e: + for op in _failed_ops(e.code, detail=e.message, ordinary=ordinary): + yield op + return + data = _outcome_data(outcome) + if ordinary and data.get("ok") is False: + for op in _failed_ops(RESULT_FAILED, detail=USER_FAILED, ordinary=True, data=data): + yield op + return + yield _querycore_final(payload, outcome) + + +async def _auto_route_ops(payload: GenerateIn) -> list[dict[str, Any]] | None: + """普通问数(intent=answer)的**保守默认路由**:高置信确定的请求直接按固定口径执行,未经模型。 + + 搭建者及以上匹配之后直接进程内固定执行;普通 user 先过**资产授权**这道闸(app/apps/access.usable_calibers:授权给它 + 的应用当前版本钉住的那些口径版本)——命中了但没授权是**终止型结局**(照实说没有授权,不回退旧的 Agent 路径:那条路 + 会去翻底表),有权则走 prepare 好的父图 + 真实 caliber_query 工具那条路(遮罩与只读由它保证)。命中之后执行失败 + (清单/权限/参数/绑定/超时等)**原样报错、绝不静默回退旧 Agent**;未命中(没匹配到、歧义、参数不全)交回 None, + 调用方照旧走模型那条路,不向用户多说什么、也不澄清。这一段不取助手模型、不读目录、不拼历史——判定本身零模型。""" + from app.api.deps import restricted + from app.db.base import SessionLocal + from app.ledger import nlchange, querycore + + ordinary = restricted() + principal, actor = _caller() + async with SessionLocal() as session: + # 和旧路径同一道门:请求带的对话读不了先照旧拒(不因为要自动路由就少判一次) + await _ensure_conversation_access(session, payload.conversation_id) + allowed = await _allowed_calibers(session, principal) + routed = await nlchange.auto_route(session, question=_question_of(payload) or payload.instruction, + allowed=allowed) + if routed is None: + return None + if routed.mode == nlchange.ROUTE_REFUSED: + return _not_permitted_ops(routed.code) + request = {key: value for key, value in routed.request.items() if key != "purpose"} + purpose = str(routed.request.get("purpose") or querycore.DEFAULT_PURPOSE) + try: + outcome = await _execute_route(session, request=request, purpose=purpose, actor=actor, prepared=ordinary, + payload=payload) + except querycore.QueryCoreRefused as e: + return _failed_ops(e.code, detail=e.message, ordinary=ordinary) + data = _outcome_data(outcome) + if ordinary and data.get("ok") is False: + return _failed_ops(RESULT_FAILED, detail=USER_FAILED, ordinary=True, data=data) + return [_querycore_final(payload, outcome)] + + async def answer_ops(payload: GenerateIn, *, catalog_view: Any = None, analysis_tools: bool = True): """生成过程:按需求起草、按需查看、自查修正、排版校验,逐条交出操作(op dict)。问数据页(经 SSE)和评测(直接迭代) 走的是这同一条路(细案 01 做法 2)。 @@ -1887,18 +2188,42 @@ async def answer_ops(payload: GenerateIn, *, catalog_view: Any = None, analysis_ 的、有分析卡的、嵌套的子工作流里用了分析能力的,照「绑定的工具不存在」那一套挡回去改(_analysis_off_issues)。缺省为真, 和以前一字不差。 - final 带 next(chat/turn.next_step:run 运行、ready 只建不跑、fail 判失败),问数据页照它走。最后多交一条 usage - (providers/usage.py):{op: usage, by_model, input_tokens, output_tokens, calls, cost_usd, + final 带 next(chat/turn.next_step:run 运行、ready 只建不跑、done 这一轮已经有了跑完的运行、fail 判失败),问数据页 + 照它走;运行不在这里发生(本函数只建图),固定执行那两条接缝的 final 带 execution,由 driver 收下那次运行。最后多交一条 + usage(providers/usage.py):{op: usage, by_model, input_tokens, output_tokens, calls, cost_usd, unpriced_calls}——这一轮助手建图(含挑表、接着写、自查修正)花了多少。前面每一条和抽出来之前逐条一样。运行不在这里, 不计。 + + K12 两条接缝在取模型之前:带了 fixed_request 就按它走(见 _fixed_request_ops);intent=answer、没带 fixed_request 时, + 先试一次**保守默认路由**(app/ledger/nlchange.auto_route)——高置信确定的请求直接按固定口径执行,命中就交一条与固定 + 请求同形状的 final(见 _auto_route_ops),未命中什么都不做、照旧走下面那条路。普通 user 也走这条接缝,只是先过资产 + 授权那道闸(见 _allowed_calibers):命中了但没授权是终止型结局,不回退、也不替它翻底表。 + + 「什么时候该看」「看什么」按身份分(K14):搭建者及以上的问数据能看已发布口径并用 use_caliber 选用;**普通使用者也 + 能看**(只列它有授权的版本),但用的是口径查询工具那条路(见 look 那一段与 copilot_context.LOOK_WHEN_QUERY_PROMPT)。 """ - from app.api.deps import restricted + from app.api.deps import current_principal, restricted from app.chat import turn from app.data.catalog_view import CatalogView from app.data.sqlcheck import load_checkers from app.db.base import SessionLocal from app.providers import usage + # K12 固定请求接缝:带了固定请求就按它走,不取模型、不读目录、不拼历史(见 _fixed_request_ops) + if payload.fixed_request: + async for op in _fixed_request_ops(payload): + yield op + return + + # K12 保守默认路由:普通问数里高置信确定的请求直接按固定口径执行,不经模型。未命中什么都不做,照旧走下面那条路; + # 普通 user 也试,但先过资产授权那道闸——命中了但没权是终止型结局,不回退旧的 Agent 路径(见 _auto_route_ops) + if payload.intent == "answer": + auto = await _auto_route_ops(payload) + if auto is not None: + for op in auto: + yield op + return + view = CatalogView.parse(catalog_view) async with SessionLocal() as session: # 带了对话的,先核对这个人能不能用它(D-d):历史、上一轮的图都从它来 @@ -1926,16 +2251,20 @@ async def answer_ops(payload: GenerateIn, *, catalog_view: Any = None, analysis_ baseline = copy.deepcopy( (payload.base_graph or {}).get("nodes") or (prev_graph or {}).get("nodes") or []) # 查看服务:读目录、读能力登记在开流之前做完。现有工作流(画布上的原图、问数据追问时上一轮的图)查过的表列在概览里。 - # 问数据另看已发布口径、可以 use_caliber 选用(next-round 02 做法 4):只给搭建者及以上——使用者的图里看得到拷进来的 - # 取数 SQL(口径的 SQL 可能写着遮罩值),这一波不给 - kinds = ("table", "capability", "caliber") if payload.intent == "answer" and not chat_user \ - else ("table", "capability") + # 问数据另看已发布口径(next-round 02 做法 4),两档按身份分(K14):搭建者及以上 look 之后可以用 use_caliber 把口径 + # 带进图(服务端把它的取数节点拷过来,图里因此看得到拷进来的 SQL);**普通使用者也看**,但只列它有授权的那些版本 + # (look/calibers 按 actor 收窄),且不给 use_caliber——改用口径查询工具,提示与工具绑定都引导到 caliber_query + kinds = ("table", "capability", "caliber") if payload.intent == "answer" else ("table", "capability") + caliber = copilot_context.CALIBER_QUERY if chat_user else copilot_context.CALIBER_COMPOSE looks = await _look_service(session, payload, sources, graph=payload.base_graph if ( - payload.base_graph or {}).get("nodes") else prev_graph, catalog_view=view, kinds=kinds) + payload.base_graph or {}).get("nodes") else prev_graph, catalog_view=view, kinds=kinds, + caliber=caliber if payload.intent == "answer" else copilot_context.CALIBER_LOOK, + actor=current_principal()) # 这一份 system 一直用到最后:接着写、自查修正都沿用,不换 system = _graph_system(sources, scope, await copilot_context.section(looks), looks, chat_user=chat_user, analysis_tools=analysis_tools) - applier = GraphApplier(nodes, edges, composer=copilot_context.composer(looks)) + # 使用者看得见口径但不能选用(K14):模型发了 use_caliber 时照实拒收、自查交回它改用口径查询工具(见 GraphApplier) + applier = GraphApplier(nodes, edges, composer=copilot_context.composer(looks), no_compose=chat_user) started = time.monotonic() gen = Generation(model, system=system, applier=applier, looks=looks, started=started, checker=GraphChecker(applier, scope=scope, sources=sources, baseline=baseline, checkers=checkers, diff --git a/backend/app/api/copilot_context.py b/backend/app/api/copilot_context.py index 56351f90..fa1ea483 100644 --- a/backend/app/api/copilot_context.py +++ b/backend/app/api/copilot_context.py @@ -11,9 +11,10 @@ **各入口看什么**(总方案 §5.3):画布、问数据看表和能力(问数据只列只读能力);发布前修复、升级证据看表,由系统按要修 的 SQL 代为查看(look 文档 D5);应用润色看工作流版本和能力(在 copilot.py 里组装)。问数据另看已发布口径(next-round 02 -做法 4:搭建者及以上;使用者发起的图里看得到拷进来的取数 SQL,这一波不给):助手可以 use_caliber 选用一份口径做骨架, -「什么时候该看」换成 LOOK_WHEN_ANSWER_PROMPT,输出协议多 USE_CALIBER_PROMPT 一段。运行时写 SQL 的 Agent 不看口径(拍板 -L2:保持独立解读,「等价已证明」才有意义)。 +做法 4),两档按身份分(K14):搭建者及以上用 use_caliber 选用一份口径做骨架(它的取数 SQL 由服务端拷进图里),「什么时候 +该看」换成 LOOK_WHEN_ANSWER_PROMPT,输出协议多 USE_CALIBER_PROMPT 一段;**普通使用者**只列它有授权的那些版本(look/calibers +按 actor 收窄),不给 use_caliber,给的是「在 agent 里调口径查询工具 caliber_query」的写法,「什么时候该看」换成 +LOOK_WHEN_QUERY_PROMPT。运行时写 SQL 的 Agent 不看口径(拍板 L2:保持独立解读,「等价已证明」才有意义)。 这里提供:look_service(按入口组装查看服务,开流之前调:读目录、读能力登记要用会话)、section(system 里数据源那一节)、 system_look(系统代为查看)、写 SQL 的硬性要求和「什么时候该看」的判断标准。 @@ -62,7 +63,14 @@ LOOK_WHEN_PROMPT = """\ · 用户说了一条数据事实:先看那张表的现有目录,再提目录修改 · 要看就先看,看完再规划,不要先搭节点再回头看;这次对话里已经看过的表直接点名看,不要只给需求""" -#: 问数据里(能看已发布口径时)的「什么时候该看」:问数据那一条按口径账本改写(next-round 02 做法 4 ④),别的照旧 +#: 问数据里口径这一档怎么用(api/copilot 按身份给): +#: look = 只看(列有授权的口径与参数,不选用、不调工具);compose = 搭建者及以上,look 后用 use_caliber 把口径带进图; +#: query = 普通使用者,look 后让 agent 调口径查询工具(caliber_query)取数——那条路不把口径的 SQL 拷进使用者的图里 +CALIBER_LOOK = "look" +CALIBER_COMPOSE = "compose" +CALIBER_QUERY = "query" + +#: 问数据里(能选用已发布口径时)的「什么时候该看」:问数据那一条按口径账本改写(next-round 02 做法 4 ④),别的照旧 LOOK_WHEN_ANSWER_PROMPT = LOOK_WHEN_PROMPT.replace( """ · 问数据:查库交给 agent 节点,它运行时会自己查表结构。只有从概览看不出该用哪个库、用户点了表名、用户说了口径时 才看一次,把看到的表名写进 agent 的提示词,运行时少走弯路""", @@ -71,6 +79,17 @@ LOOK_WHEN_ANSWER_PROMPT = LOOK_WHEN_PROMPT.replace( 口径,交给 agent 去查,系统会自动拿它的 SQL 和口径对账。查库交给 agent 时它运行时会自己查表结构:只有从概览看不出 该用哪个库、用户点了表名时才看表,把看到的表名写进 agent 的提示词""") +#: 问数据里**普通使用者**那一档的「什么时候该看」(K14):先看有授权的口径,对得上就让 agent 调口径查询工具取数—— +#: 这条路上没有 use_caliber(把口径的取数 SQL 拷进使用者的图是搭建者才做的事),数得来自一次固定口径执行 +LOOK_WHEN_QUERY_PROMPT = LOOK_WHEN_PROMPT.replace( + """ · 问数据:查库交给 agent 节点,它运行时会自己查表结构。只有从概览看不出该用哪个库、用户点了表名、用户说了口径时 + 才看一次,把看到的表名写进 agent 的提示词,运行时少走弯路""", + """ · 问数据:先看已发布口径(kind 写 caliber)——列出来的都是**你有授权的**那些版本。问法和某张口径对得上时 + **不要自己写取数 SQL**:搭一个 agent 节点,在它的 prompt 里让它照查看结果的「取数写法」调用口径查询工具算出那几个 + 指标(口径身份、指标 id、inputs 照抄;相对时间先取当前日期再折算成开始/结束),交回的指标值写进报告。口径只覆盖问题 + 的一部分时,其余交给 agent 查底表补;问题里有多出口径没有的条件(含退款、只看新客这类)时不要套口径,交给 agent 去查。 + 查库交给 agent 时它运行时会自己查表结构:只有从概览看不出该用哪个库、用户点了表名时才看表,把看到的表名写进提示词""") + #: 问数据里输出协议多的一段:选用口径(ledger/compose.py)。只在这一轮能看已发布口径时接在协议后面。 #: 两个 id 写清楚(真实验收里模型第一次常把 card 写成自己起的 c1,被拒之后才改对):card 是那一版工作流图里口径卡的节点 id, #: 照抄查看结果;id 是这次选用自己起的名字,生成的口径卡用它当节点 id @@ -91,13 +110,15 @@ SYSTEM_LOOK_UPGRADE_NEED = "要升级的工作流里,查库节点的 SQL 用 async def look_service(sources: list[Any], *, spec: ModelSpec | None, graph: Mapping[str, Any] | None = None, kinds: tuple[str, ...] = ("table", "capability"), answer: bool = False, catalog_view: Any = None, trail: Mapping[str, Any] | None = None, - session: Any = None) -> LookService: + session: Any = None, actor: Any = None, caliber: str = CALIBER_LOOK) -> LookService: """按入口组装这一轮的查看服务。读目录、读能力登记都用各自的短会话,开流前后都能调。 spec 是助手的模型规格:挑选模型第一次要用时才按它拿(关思考、额度按 look/pick.PICK_MAX_TOKENS)。graph 是现有工作流,概览里列出它查过的表。 answer:问数据(意图为回答),能力只列只读的。catalog_view:表详情里给哪一份数据目录(data/catalog_view.py),不给是当前目录。 trail:按需加入探查范围时的留痕(哪一轮对话:{conversation_id};谁取这次请求的身份)。 - kinds 里有 caliber 时用 session(调用方开流之前的会话)读已发布口径,问数据里另判能不能组合(look/calibers 的 compose)。 + kinds 里有 caliber 时用 session(调用方开流之前的会话)读已发布口径:compose 那一档另判能不能组合(look/calibers + 的 compose),query 那一档只给按口径查询工具取数的写法(普通使用者,K14)。`actor` 是这次是谁:交给 CaliberKind.load + 按资产授权收窄(普通使用者只列有授权的那些版本;不给就取当前请求的身份)。 """ from app.look.calibers import CaliberKind @@ -108,18 +129,23 @@ async def look_service(sources: list[Any], *, spec: ModelSpec | None, graph: Map if "capability" in kinds: made.append(await CapabilityKind.load(picker=picker, read_only=answer)) if "caliber" in kinds and session is not None: - made.append(await CaliberKind.load(session, picker=picker, compose=answer)) + made.append(await CaliberKind.load(session, picker=picker, compose=caliber == CALIBER_COMPOSE, actor=actor, + query=caliber == CALIBER_QUERY)) return LookService(made) def composing(looks: LookService) -> bool: - """这一轮能不能选用已发布口径(问数据里读好了能组合的口径卡)。""" + """这一轮能不能选用已发布口径(问数据里读好了能组合的口径卡,搭建者及以上那一档)。""" kind = looks.kinds.get("caliber") - return kind is not None and getattr(kind, "options", None) is not None + return (kind is not None and getattr(kind, "options", None) is not None + and not getattr(kind, "query", False)) def look_when(looks: LookService) -> str: - """「什么时候该看」:能选用已发布口径的问数据用改写过的那一份。""" + """「什么时候该看」:问数据里能选用已发布口径的用一份,普通使用者(不能 use_caliber、要让它调口径查询工具)用另一份。""" + kind = looks.kinds.get("caliber") + if kind is not None and getattr(kind, "query", False): + return LOOK_WHEN_QUERY_PROMPT return LOOK_WHEN_ANSWER_PROMPT if composing(looks) else LOOK_WHEN_PROMPT @@ -155,6 +181,7 @@ async def system_look(looks: LookService, graph: Mapping[str, Any] | None, sourc __all__ = [ - "LOOK_WHEN_ANSWER_PROMPT", "LOOK_WHEN_PROMPT", "SQL_RULES_PROMPT", "SYSTEM_LOOK_FIX_NEED", "SYSTEM_LOOK_UPGRADE_NEED", + "CALIBER_COMPOSE", "CALIBER_LOOK", "CALIBER_QUERY", "LOOK_WHEN_ANSWER_PROMPT", "LOOK_WHEN_PROMPT", + "LOOK_WHEN_QUERY_PROMPT", "SQL_RULES_PROMPT", "SYSTEM_LOOK_FIX_NEED", "SYSTEM_LOOK_UPGRADE_NEED", "USE_CALIBER_PROMPT", "composer", "composing", "graph_tables", "look_service", "look_when", "section", "system_look", ] diff --git a/backend/app/api/copilot_gen.py b/backend/app/api/copilot_gen.py index 02557718..1a15b26a 100644 --- a/backend/app/api/copilot_gen.py +++ b/backend/app/api/copilot_gen.py @@ -72,6 +72,9 @@ OP_NAMES = frozenset({ "bp_ask", "bp_set", "bp_add", "bp_remove", "bp_template", "fill_joint", }) +#: 这一轮看得见口径但**不能选用**(普通使用者的问数据)时的拒收原因与改法:改用口径查询工具,别自己拼取数 SQL +NO_COMPOSE_TEXT = "这一轮不能选用口径:把口径的取数 SQL 拷进图里只有搭建者及以上能走" + def _op_text(line: str) -> str: """一行里要按操作读的那段:去掉首尾空白和同一行上的围栏。只有围栏的行(```、```json)交回空串。""" @@ -533,15 +536,20 @@ class GraphApplier: 第一个取数节点(入口还没加的话,等入口加了再接);转给界面的只是那一条 use_caliber,带上 result(选用了哪一版、生成了 哪几个节点)。不合规的拒收:result 写原因、照样转给界面(过程里照实写一行),原因记进 refused,自查时交回模型改 (GraphChecker.issues)。没有 composer 的入口(画布、发布前修复、升级)use_caliber 不认,照旧当认不出的操作丢掉。 + + no_compose:这一轮**看得见口径但不能选用**(普通使用者的问数据,K14:拷口径的取数 SQL 进图只有搭建者及以上能走)。 + 这时 use_caliber 不丢掉也不落地,照实拒收、自查时交回模型改用口径查询工具(口径清单与取数写法 look 已经给了)。 """ def __init__(self, nodes: dict[str, dict[str, Any]], edges: list[dict[str, Any]], *, patches: bool = True, - questions: bool = False, composer: Any = None) -> None: + questions: bool = False, composer: Any = None, no_compose: bool = False) -> None: self.nodes = nodes self.edges = edges self.patches = patches self.questions_mode = questions self.composer = composer + #: 这一轮看得见口径但不能选用(见类说明):use_caliber 拒收而不是当认不出的操作丢掉 + self.no_compose = no_compose #: 选用口径实例化出来的段:[(第一个取数节点, 全部节点 id)],接入口用 self.composed: list[tuple[str, list[str]]] = [] #: 这一轮选用过的口径(调用审计 caliber.use 用):[{workflow_id, version, card, metrics, inputs}]。 @@ -596,8 +604,13 @@ class GraphApplier: self.autorun = op.get("run") is not False self.seen.append(op) return Applied(False, True) - if kind == "use_caliber" and self.composer is not None: - return self._use_caliber(op) + if kind == "use_caliber": + if self.composer is not None: + return self._use_caliber(op) + if self.no_compose: + # 看得见口径但不能选用:照实拒收(自查时交回模型改用口径查询工具),不静默丢掉 + self.refused.append({"op": op, "message": NO_COMPOSE_TEXT, "no_compose": True}) + return Applied(False, True) if kind == "add_edge" and self._was_wired(op.get("edge") or {}): # 入口 → 取数这条系统已经接上了 return Applied(False, False) @@ -917,6 +930,9 @@ def _profile_facts(row: Any) -> Any: #: 选用口径被拒时交回模型的说法 _REFUSED_FOR_MODEL = ("上一次的 use_caliber 被拒收:{message}。按原因改正后重新输出 use_caliber(id 可以沿用);这份口径对不上" "问法的话就不要选用,交给 agent 查") +_NO_COMPOSE_FOR_MODEL = ("这一次不能选用口径({message}):不要重新输出 use_caliber,也不要把口径的取数 SQL 抄进图里。" + "改用口径查询工具 {tool}——在一个 agent 节点的 prompt 里让它照 look 交回的「取数写法」调它取数," + "交回的指标值写进报告") def _refused_issues(applier: Any) -> list[dict[str, Any]]: @@ -924,10 +940,17 @@ def _refused_issues(applier: Any) -> list[dict[str, Any]]: if not isinstance(applier, GraphApplier): return [] from app.ledger.compose import REFUSED + from app.ledger.querycore import CALIBER_QUERY - return [{"level": "error", "node_id": None, "edge_id": None, "field": None, "code": REFUSED, - "message": f"没有选用口径:{r['message']}", "for_model": _REFUSED_FOR_MODEL.format(message=r["message"])} - for r in applier.unreported()] + out: list[dict[str, Any]] = [] + for r in applier.unreported(): + if r.get("no_compose"): + model = _NO_COMPOSE_FOR_MODEL.format(message=r["message"], tool=CALIBER_QUERY) + else: + model = _REFUSED_FOR_MODEL.format(message=r["message"]) + out.append({"level": "error", "node_id": None, "edge_id": None, "field": None, "code": REFUSED, + "message": f"没有选用口径:{r['message']}", "for_model": model}) + return out APP_REPAIR_PROMPT = ( diff --git a/backend/app/api/evidence.py b/backend/app/api/evidence.py index fa2bfbf5..eb5677fa 100644 --- a/backend/app/api/evidence.py +++ b/backend/app/api/evidence.py @@ -459,12 +459,21 @@ def _cell_name(alias: Any, locator: dict[str, Any]) -> str: return f"{alias}.r{locator['row']}.{locator['column']}" -def _query_alias(catalog: dict[str, Any], artifact: Any) -> str | None: - """这份快照在报告目录里的全局编号。agent 字段的 ref 是那个节点内部的编号,靠工件对上。""" +def _query_alias(catalog: dict[str, Any], artifact: Any, entry: dict[str, Any] | None = None) -> str | None: + """这份快照在报告目录里的全局编号。agent 字段的 ref 是那个节点内部的编号,靠工件对上。 + + entry 是已知的那一条目录条目(引用就是它)时优先用它的编号:同一份快照被执行两次(循环、两个节点写同一 + 条 SQL)时 artifact 一样,只按 artifact 找会把 Q2 也认成 Q1。 + """ if not artifact: return None - return next((alias for alias, e in catalog.items() if e.get("kind") == "query" and e.get("artifact") == artifact), - None) + if isinstance(entry, dict): + alias = entry.get("alias") + found = catalog.get(alias) if isinstance(alias, str) else None + if isinstance(found, dict) and found.get("kind") == "query" and found.get("artifact") == artifact: + return alias + return next((alias for alias, e in catalog.items() if isinstance(e, dict) and e.get("kind") == "query" + and e.get("artifact") == artifact), None) def _input_cell(item: dict[str, Any], catalog: dict[str, Any]) -> str: @@ -841,7 +850,7 @@ async def _chain(seg: dict[str, Any], doc: dict[str, Any], sealed: _Sealed, # 只有直接引用的单元格才可能推断来源(P4-SPEC 2.8.2)。指标链里的查询步骤不带:指标片段的推断来源只会 # 回「不是单元格」,带上提示等于让界面白发一次请求 return await _query_steps(str(entry.get("artifact") or ""), [(locator.get("row"), locator.get("column"))], - doc, sealed, masks, hint=doc.get("provenance") == DOC_PROVENANCE) + doc, sealed, masks, hint=doc.get("provenance") == DOC_PROVENANCE, entry=entry) if cite.get("kind") == "input": name = (cite.get("locator") or {}).get("field") inputs = _input_payloads(sealed) @@ -1126,7 +1135,7 @@ async def _analysis_inputs(alias: str, result: dict[str, Any], catalog: dict[str **({"phrase": parent.get("phrase")} if parent else {})) steps.append(step) continue - query = sealed.queries.get(artifact) + query = sealed.query_at(artifact, node_id=item.get("node_id"), execution_id=item.get("execution_id")) step.update(query=_catalog_alias_of(catalog, artifact), node_id=(query or {}).get("node_id"), sealed=sealed.trusted and query is not None) if role in totals and totals[role] in values: @@ -2785,9 +2794,12 @@ def _leaf_of(leaf: Any) -> Any: async def _query_step(artifact: str, cells: list[tuple[Any, Any]], doc: dict[str, Any], sealed: _Sealed, - masks: _Masks, *, hint: bool = False) -> dict[str, Any]: + masks: _Masks, *, hint: bool = False, entry: dict[str, Any] | None = None) -> dict[str, Any]: """查询步骤:被引用的格所在的行加前后各 WINDOW 行,高亮那几格,遮掉数据源设了遮罩的列。 + entry 是引用落到的那条目录条目:同一份快照被执行两次(循环、两个节点写同一条 SQL)时 artifact 一样, + 按 entry 的编号与执行身份(node_id / exec / execution_id)认这一次,别把 Q2 认成 Q1。 + 快照只认封存范围内的事件交回过的那些(tool.end.query_artifact、node.finished.evidence 的 query 条目);目录里写着、事件里追不到的,照实说不认,一行都不给。 @@ -2798,11 +2810,17 @@ async def _query_step(artifact: str, cells: list[tuple[Any, Any]], doc: dict[str checks:快照里记下的 SQL 检查结果(数据目录阶段 2B,见 _query_checks),只在查出问题时有这个键。 """ catalog = doc.get("catalog") or {} - alias = _query_alias(catalog, artifact) - entry = catalog.get(alias, {}) if alias else {} - info = sealed.queries.get(artifact) if artifact else None + alias = _query_alias(catalog, artifact, entry) + entry = catalog.get(alias, {}) if alias else (entry or {}) + # 第几次执行:新条目可能把「第几次」记在 attempt 上(老条目记 exec),两个都认 + nth = entry.get("exec") if entry.get("exec") is not None else entry.get("attempt") + info = sealed.query_at(artifact, node_id=entry.get("node_id"), exec_no=nth, + execution_id=entry.get("execution_id")) if artifact else None rows_hit = sorted({r for r, _ in cells if isinstance(r, int)}) cols_hit = list(dict.fromkeys(str(c) for _, c in cells if c)) + # 执行身份(K10):只给新条目的那几项(query_id / execution_id / attempt)——exec 老条目也有, + # 露出来等于改了老运行、老文档的形状。未封存的步骤同样一个键都不加 + identity = {k: info.get(k) for k in ("query_id", "execution_id", "attempt")} if info is not None else {} step: dict[str, Any] = { "step": "query", "alias": alias, "artifact": artifact or None, "node_id": (info or {}).get("node_id") or entry.get("node_id"), @@ -2813,6 +2831,9 @@ async def _query_step(artifact: str, cells: list[tuple[Any, Any]], doc: dict[str "highlight": {"rows": rows_hit, "cols": cols_hit, "cells": [[r, str(c)] for r, c in dict.fromkeys(cells) if isinstance(r, int) and c]}, "masked": [], "hash_ok": None, "sealed": False, + # 执行身份(K10):同一份快照被执行两次时,靠这三样才说得出这一格是哪一次查的。老运行、老条目 + # (一个都没有)不加这几个键,步骤形状和以前一字不差 + **{k: v for k, v in identity.items() if v is not None}, } if info is None: return {**step, "note": UNSEALED_QUERY} @@ -2970,13 +2991,15 @@ MERGE_DEPTH = 4 async def _query_steps(artifact: str, cells: list[tuple[Any, Any]], doc: dict[str, Any], sealed: _Sealed, - masks: _Masks, *, hint: bool = False, depth: int = 0) -> list[dict[str, Any]]: + masks: _Masks, *, hint: bool = False, depth: int = 0, + entry: dict[str, Any] | None = None) -> list[dict[str, Any]]: """查询步骤;快照是合并结果时,后面接上被引用的格追到的那几个输入的查询步骤(高亮追到的那一格)。 追不到的格不接任何输入步骤:合并步骤的 merge.traced 里照实写「没有逐格来历」,只给表级来历。输入步骤带 merged_into(合并结果的编号),界面据此标明它是哪次合并的输入。不是合并结果的快照,返回的就是原来那一个步骤。 + entry 指这次引用落到的那条目录条目(同一份快照被执行两次时用来认是哪一次)。 """ - step = await _query_step(artifact, cells, doc, sealed, masks, hint=hint) + step = await _query_step(artifact, cells, doc, sealed, masks, hint=hint, entry=entry) traced = [t for t in (step.get("merge") or {}).get("traced") or [] if t.get("input")] if not traced or depth >= MERGE_DEPTH: return [step] diff --git a/backend/app/api/ledger.py b/backend/app/api/ledger.py index f5aa1300..f17d687c 100644 --- a/backend/app/api/ledger.py +++ b/backend/app/api/ledger.py @@ -9,7 +9,9 @@ - GET /api/ledger/stats(router,搭建者):账本自身给出的统计 E1–E4,从比对工件、运行、审计现算(app/ledger/stats.py); - POST /api/ledger/answers/{run_id}/issue(answers_router,登录即可,第 3 波):按口径正式出具(app/ledger/issue.py,拍板 L1、L5:参数只从比对工件取,使用者只能按他有权使用的应用固定着的版本出具); -- POST /api/ledger/answers/{run_id}/reconcile(同上):口径对账,点开才跑一次确定性派生的只读图(app/ledger/reconcile.py); +- POST /api/ledger/answers/{run_id}/reconcile(同上):口径对账,点开才跑一次确定性派生的只读图(app/ledger/reconcile.py)。 + 它派生出来的图实际执行的就是点名的这一版口径:**普通使用者先要有这一版的资产授权**(K14,`ensure_caliber_use`:缺了在 + 派生、发起之前就 403 querycore_not_authorized,一条运行都不起,也不换路、不退底表);builder / admin / 关登录照旧放行; - POST /api/ledger/answers/{run_id}/reconcile/{reconcile_id}/feedback(同上,第 4 波):对账结果上的「说明有用 / 看不懂」 (app/ledger/feedback.py,统计 E2); - GET /api/ledger/certify-queue、POST /api/ledger/certify-queue/dismiss(router,搭建者,第 3 波):可沉淀的问题、「不是口径」 @@ -24,6 +26,28 @@ 后台自动只读试跑;草稿页给「定义 + 数 + 原文引用」。模型一轮只起草一组指标,一轮覆盖不完就带着 uncovered 续跑, 一组一个取数节点挂到同一张口径卡上(见 _extract_in_background)。attach 保留为辅助入口:已经有跑对的答案时让它认 这份定义(app/ledger/docattach.py)。 + 读草稿给出这份草稿的权威口径卡(card_id,多张时是下游契约声明的那张)和基准版本(revision = Workflow.version); + 改草稿(PATCH)对已经接管到工作流上的这类草稿按 K02 的写入保护走:要带 expected_revision、目标卡要明确、带 + request_id 的按主体 + 工作流 + 目标卡幂等(见 patch_draft 和 app/apps/versions.py 的写入幂等一节)。 + PATCH 的 operations 是 K03 的字段变更:按稳定 metric_id + 字段路径改一处(app/ledger/changes.py 的白名单和语义), + 和整份换指标(metrics)互斥;改在图的深拷贝上,回执里带变更分类、影响指标和失效说明。 +- GET /api/ledger/drafts/{id}/validations、POST …/validations/{record_id}/review(router,搭建者,K05):验证记录 + (追加存储,app/ledger/validation.py)和最小审阅(app/ledger/review.py)。每条记录绑着这次试跑的定义/绑定/取数语义 + 依据,covers_current 读的时候现算;没有独立期望只记 observed,样例匹配不等于批准。审阅的审批人只来自服务端身份。 + 草稿详情另给 field_baseline(K05 的字段基线 B:首次接受导入时按 metric_id + field_path 存下的不可变工件引用, + app/ledger/fieldbaseline.py)和 validation(验证总情况:覆盖判断、最新一条、审阅结论)。 +- POST /api/ledger/querycore(router,搭建者,K09):进程内 QueryCore 固定执行(app/ledger/querycore.py)——按一份 + 已发布的固定口径(点名哪一版、或读一次推荐版并当场固定)跑一次:K08 闭包选指标、K01 参数语义、只读边界,交回 + 类型化指标、发布/manifest 引用、闭包身份、参数解释与哈希、数据时点与质量、每条查询的证据引用。用途是宿主常量 + (这个入口固定 compose/探索,客户端传不了 purpose / role / actor),要正式身份的是 K10 父 Run 的宿主入口 + (querycore.execute_formal,同一套 judge)。 +- POST /api/ledger/drafts/{id}/change-proposal、POST …/nl-change(router,搭建者,K12):受限的自然语言修改 + (app/ledger/nlchange.py)。前者**只读**:一句话 → K03 同一形状的 operations + 影响摘要 + 澄清项;后者默认只预览, + confirm=true 才按同一批操作落一版,且只是一层薄适配——翻成一次 DraftPatchIn 交给现有变更服务(patch_draft)。 + 说不清(含糊业务条件、没匹配能力)回 409 并带澄清项,一条操作都不落。 +- POST /api/ledger/ask(router,搭建者,K12):Ask Data 的固定请求路由。已经明确 workflow/card/metric_ids/inputs 的 + 请求直接进 QueryCore(路由只把版本固定一次,不重复解析/规划,内部 LLM 仍为 0);没有匹配口径就进探索、含糊业务 + 条件先澄清、业务条件和匹配到的口径对不上就明确说「先改口径」,绝不静默换计算规则。 这几个新接口都不放给访问密钥(auth/keys.KEY_ROUTES 不登记)。 """ from __future__ import annotations @@ -32,15 +56,18 @@ import asyncio import copy import logging import re +from collections.abc import Iterable, Mapping from typing import Any from datetime import datetime from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query -from pydantic import BaseModel, Field +from pydantic import BaseModel, ConfigDict, Field from sqlalchemy import select +from sqlalchemy.exc import IntegrityError from sqlalchemy.ext.asyncio import AsyncSession +from app.api.coded import CodedHTTPException from app.db.base import SessionLocal, get_session from app.db.models import CaliberDraft, Chunk, DataSource, Document, Run, Workflow, WorkflowVersion from app.db.models_process import ActionRecord @@ -60,6 +87,55 @@ runs_router = APIRouter(prefix="/api/runs", tags=["ledger"]) answers_router = APIRouter(prefix="/api/ledger/answers", tags=["ledger"]) +async def ensure_caliber_use(session: AsyncSession, actor: Any, targets: Iterable[tuple[str, Any]], *, + what: str) -> None: + """普通使用者按口径执行之前的**共享那一道**(K14):这次实际要执行的每一版口径都要有资产授权到 use 及以上。 + + - 只对「普通使用者」成立(`auth/chat_policy.restricted_actor`:开登录后不是 builder / admin 的那一档;actor 可以是当前 + Principal,也可以是用户名)。builder / admin / 关登录在这里**显式放行**——这几档本来就能按口径执行,它们的角色不写进 + 只认授权的 `apps/access.caliber_role`; + - 缺一个就 403 `querycore_not_authorized`(`what` 说明是哪次操作),**在这个入口发起任何运行之前**:不换路、也不退回 + 探索底表;problems 里逐条写清缺的是哪一版; + - targets 是「这次真正会执行的那几版」`(workflow_id, version)`:调用方按自己派生出来的图给,别把没执行的版本列进来 + (召回那一批同时执行新旧两版,两版都要过); + - 一处判定:各入口(对账、以后别的派生执行)都调这一个函数,不各写一套角色逻辑。**只读地看历史**(账本、对过账的运行、 + 证据、运行记录)不走这一道(下面那个 `restricted_actor` 之外还有 `can_read_run` 那条线管读);按口径**正式出具**仍走它 + 自己那一套(`ledger/issue`:资产授权 + `publications.judge`),不在这里重判。 + """ + from app.apps.access import at_least, caliber_role + from app.auth.chat_policy import effective_actor, restricted_actor + from app.ledger import querycore + + wanted: list[tuple[str, int]] = [] + for workflow_id, version in targets: + try: + wanted.append((str(workflow_id), int(version))) + except (TypeError, ValueError): # 版本认不成整数:交给那个入口自己的说法(这里不替它猜) + continue + if not wanted: + return + who = effective_actor(actor) + if not await restricted_actor(session, who): + return + missing: list[dict[str, Any]] = [] + for workflow_id, version in wanted: + role = await caliber_role(session, who, workflow_id, version) + if not at_least(role, "use"): + missing.append({"code": querycore.NOT_AUTHORIZED, "workflow_id": workflow_id, "version": version, + "role": role or ""}) + if not missing: + return + names = dict((await session.execute(select(Workflow.id, Workflow.name).where( + Workflow.id.in_({m["workflow_id"] for m in missing})))).all()) + listed = "、".join(f"「{names.get(m['workflow_id']) or m['workflow_id']}」v{m['version']}" for m in missing[:4]) + raise CodedHTTPException( + 403, + f"没有权限:{what}要执行的这几版口径没有授权给你使用:{listed}" + + (f" 等 {len(missing)} 版" if len(missing) > 4 else "") + + "。用一份已发布的口径要有应用授权(让搭建者把固定着这一版口径的应用授权给你,至少「使用」)", + querycore.NOT_AUTHORIZED, extra={"problems": missing}) + + @router.get("/workflow-versions/{workflow_id}/{version}") async def workflow_version(workflow_id: str, version: int, session: AsyncSession = Depends(get_session) ) -> dict[str, Any]: @@ -175,18 +251,26 @@ class ReconcileIn(BaseModel): @answers_router.post("/{run_id}/reconcile", status_code=201) -async def reconcile_answer(run_id: str, payload: ReconcileIn) -> dict[str, Any]: +async def reconcile_answer(run_id: str, payload: ReconcileIn, + session: AsyncSession = Depends(get_session)) -> dict[str, Any]: """口径对账(app/ledger/reconcile.py):按那一版口径确定性派生只读图,发起一次探索运行(来源 reconcile),差值在对账卡 里算。参数是推断出来的、不全的要先核对(409,code ledger_reconcile_check_inputs);认不出列怎么配的要人选(409, - ledger_reconcile_needs_pairs);多行时维度是遮罩列、键不唯一照实拒绝(409)。""" + ledger_reconcile_needs_pairs);多行时维度是遮罩列、键不唯一照实拒绝(409)。 + + 派生图实际执行的就是点名的这一版口径(`reconcile.reconcile` 按 workflow_id/version 读 pinned,内联进对账图的那一段): + **普通使用者**要先有这一版的资产授权(K14,`ensure_caliber_use`),缺了在派生、发起之前就 403 + `querycore_not_authorized`——一条运行都不起,也不换路、不退回探索底表;builder / admin / 关登录照旧放行。""" from app.api.coded import CodedHTTPException from app.api.deps import current_principal from app.ledger import reconcile as ledger_reconcile + principal = current_principal() + # 发起之前先过共享那一道(对账这一版实际会执行的口径版本):缺授权当场 403,下面一行都不会走到 + await ensure_caliber_use(session, principal, [(payload.workflow_id, payload.version)], what="口径对账") try: run = await ledger_reconcile.reconcile(run_id, ledger_reconcile.Request( query=payload.query, workflow_id=payload.workflow_id, version=payload.version, inputs=payload.inputs, - confirm=payload.confirm, pairs=payload.pairs), principal=current_principal()) + confirm=payload.confirm, pairs=payload.pairs), principal=principal) except ledger_reconcile.ReconcileRefused as e: raise CodedHTTPException(e.status_code, e.message, e.code, extra=e.extra) from e return {"run_id": run.id, "reconciled": ledger_reconcile.reconciled_view(run)} @@ -230,7 +314,11 @@ async def recall_batches(workflow_id: str, version: int, session: AsyncSession = async def recall_continue(workflow_id: str, version: int, session: AsyncSession = Depends(get_session) ) -> dict[str, Any]: """接着算:把还没重算的组再发起一批(每批 recall_limit 组,上限是 0 时按缺省的组数),交回发起了的召回运行和新的批次 - 情况。都算过了的、这一版已经不是当前发布版的(之后又发布了更新的版本)回 409,detail 写为什么。""" + 情况。都算过了的、这一版已经不是当前发布版的(之后又发布了更新的版本)回 409,detail 写为什么。 + + 这一组接缝是**搭建者专用**(main.py 给 ledger.router 挂的是 require_role("builder"),使用者到不了这里);叫起的召回运行 + 一次同时执行**新旧两版**口径(旧版那几组的卡 + 这一版,ledger/recall.build_graph),若以后开放给使用者,先按这两版过 + `ensure_caliber_use`(对账那条路就是这么做的:缺任何一版都在发起前 403 querycore_not_authorized)。""" from app.api.coded import CodedHTTPException from app.api.deps import current_principal from app.ledger import recall @@ -282,23 +370,47 @@ async def calibers(workflow_id: str | None = None, session: AsyncSession = Depen JSON Schema、指标、依赖的表和发布时钉住的数据目录/结构版本、能不能组合、出具策略。workflow_id 可只列一个工作流。 不返回取数 SQL、不返回参数值(SQL 里可能写着遮罩值)。issuance 只描述这一版的策略(级别、有没有人工节点或写外部系统), - 不代表这次运行一定能出具:全局自动出具开关、每日上限这类运行时条件不在这里判。""" + 不代表这次运行一定能出具:全局自动出具开关、每日上限这类运行时条件不在这里判。 + + 每一条另给 binding(K04 的业务绑定能力描述,和单条接口交同一份):能按字段改哪些业务定义、允许值和说法、这一版 + 现在的值、定义和取数实现的同步状态(aligned / needs_update / unsupported / unbound)、不支持的原因和该做什么。 + aligned 只说定义和实现同步,不等于业务验证通过;这里也不返回受控模板。""" from app.ledger.descriptor import list_calibers as list_descriptors - return {"calibers": await list_descriptors(session, workflow_id=workflow_id)} + made = await list_descriptors(session, workflow_id=workflow_id) + return {"calibers": [await _with_binding(session, item) for item in made]} + + +async def _with_binding(session: AsyncSession, made: dict[str, Any] | None) -> dict[str, Any] | None: + """给一条口径描述补上 K04 的绑定能力描述(列表和单条交同一份:读那一版的图现算)。 + + **不给受控模板、不给 snippets、不给 SQL**:那几样是作者侧的实现细节,界面和外部集成只需要知道业务值和状态。""" + if made is None: + return None + from app.apps.versions import version_row + from app.ledger import bindings + + row = await version_row(session, str(made.get("workflow_id") or ""), int(made.get("version") or 0)) + graph = (row.graph if row is not None else None) or {} + return {**made, "binding": bindings.capability(graph, str((made.get("card") or {}).get("node_id") or ""))} @router.get("/calibers/{workflow_id}/{version}/{node_id}") async def caliber_descriptor(workflow_id: str, version: int, node_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: """一张源头口径卡的描述(形状同列表里的一条)。工作流不存在、这一版没发布过或已退役、节点不是源头口径卡(转抄卡也算) - 回 404。同样不返回 SQL、参数值;issuance 只描述版本策略,不代表这次运行一定能出具。""" + 回 404。同样不返回 SQL、参数值;issuance 只描述版本策略,不代表这次运行一定能出具。 + + 另给 binding(K04 的服务端能力描述):能按字段改的业务定义(时间口径、退款处理)、每个字段的允许值和说法、 + 这一版绑定里现在的值、定义和取数实现的同步状态(aligned / needs_update / unsupported / unbound)、不支持时的 + 原因、影响到的指标和取数节点、以及该做什么。**aligned 只说定义和实现同步,不等于业务验证通过**;这里也不返回 + 受控模板和 SQL(那是作者侧的实现细节)。""" from app.ledger.descriptor import caliber_descriptor as descriptor_of made = await descriptor_of(session, workflow_id, version, node_id) if made is None: raise HTTPException(404, "没有这份口径:工作流不存在、这一版没发布过或已退役,或者节点不是源头口径卡") - return made + return await _with_binding(session, made) class RuleCompileIn(BaseModel): @@ -333,18 +445,27 @@ async def trial_caliber(workflow_id: str, version: int, node_id: str, payload: T session: AsyncSession = Depends(get_session)) -> dict[str, Any]: """按固定版本试跑一份口径:派生只读小图(取数 + 口径卡),跑一次探索运行,返回指标值和运行 id。 - 试跑不是正式出具:来源记 trial,不进使用统计、不自动出具;参数按入口 Schema 校验,缺的补缺省值。不能派生的口径 - (输入不是查库结果里的格、取数模板引用了运行时变量……)照实回 409。最多等 30 秒;还没跑完就回 running,前端按 - run_id 去看运行。""" + 试跑不是正式出具:来源记 trial,不进使用统计、不自动出具;参数按入口 Schema 校验,缺的补缺省值;参数完整性按 + ledger/params 同一套判断(缺参数、未声明参数、值承载不了),不合规在**发起运行之前**回结构化 422(code 是 + missing_parameter / undeclared_parameter / …),一条 SQL 都不会发出去。不能派生的口径(输入不是查库结果里的格、 + 取数模板引用了运行时变量……)照实回 409。最多等 30 秒;还没跑完就回 running,前端按 run_id 去看运行。""" from app.api.deps import current_principal from app.apps.forms import input_schema, validate_form from app.engine.runner import run_manager + from app.ledger import params + from app.ledger.derive import UNDECLARED_PARAMETER as derive_undeclared_code from app.ledger.derive import NotDerivable, caliber_probe, load_pinned from app.tools.datasource import READ_ONLY_OPTION try: pinned = await load_pinned(session, workflow_id, int(version), node_id) except NotDerivable as e: + # 取数模板引用了入口没声明的字段(undeclared_parameter):这是参数契约的问题,按参数完整性回结构化 422, + # 并把逐条问题原样交回(problems);别的不能派生的原因照旧 409 + if e.code == derive_undeclared_code: + raise CodedHTTPException(422, e.message, params.UNDECLARED, + extra=({"problems": [p.as_dict() for p in e.problems]} if e.problems else None) + ) from None raise HTTPException(409, e.message) from None if not pinned.published or pinned.retired: raise HTTPException(409, "这一版没有发布或已退役,不能试运行") @@ -353,10 +474,19 @@ async def trial_caliber(workflow_id: str, version: int, node_id: str, payload: T unknown = sorted(str(k) for k in payload.inputs if str(k) not in known) if unknown: raise HTTPException(422, f"不认识的入口字段:{'、'.join(unknown)}") + # 收值和组合式问数同一份(params.provided):显式传的空串算没给——字段又没声明缺省值时就是缺参数(下面拒), + # 声明了 default="" 的照缺省值走(作者写的就是「空值不过滤」) values = {str(f["name"]): f.get("default") for f in fields if f.get("default") not in (None, "")} - values.update({str(k): v for k, v in payload.inputs.items()}) + values.update(params.provided(payload.inputs)) if errors := validate_form(input_schema(fields), values): raise HTTPException(422, ";".join(str(e.get("message")) for e in errors[:5])) + # 参数完整性:模板里的每个参数这次都要有值(可选、没有缺省值的也算缺),引用的字段入口都得声明过, + # 承载不了的值明确拒——都在发起运行之前判,缺参/未声明不会走到「发出 SQL 才发现」 + problems = params.check_nodes(pinned.fetches, fields=pinned.entry_fields, values=values, + where=f"口径「{pinned.workflow_name}」的入口") + if problems: + raise CodedHTTPException(422, params.describe(problems), problems[0].code, + extra={"problems": [p.as_dict() for p in problems]}) graph = caliber_probe(pinned).graph principal = current_principal() @@ -385,6 +515,196 @@ async def trial_caliber(workflow_id: str, version: int, node_id: str, payload: T return out +# -------------------------------------------------------------------------- +# 进程内 QueryCore 固定执行(app/ledger/querycore.py,K09) +# -------------------------------------------------------------------------- + + +class QueryCoreIn(BaseModel): + """这一次固定执行要什么:口径身份(workflow + card)、要算的指标、类型化入口取值、预算与 trace。 + + **不收 purpose / role / actor**:用途由宿主常量定(这个接口固定成 compose/探索),认证主体来自服务端身份。 + 请求体里多传的字段一律不看(不认识的键被忽略),提不了权。""" + + workflow_id: str + card_id: str + metric_ids: list[str] = Field(min_length=1) + inputs: dict[str, Any] = Field(default_factory=dict) + version: int | None = None + budget: dict[str, Any] | None = None + trace: str | None = None + + +@router.post("/querycore") +async def querycore_execute(payload: QueryCoreIn, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """按一份**已发布的固定口径**进程内跑一次(app/ledger/querycore.py):交回类型化指标、实际发布/manifest 引用、 + selection/closure 身份、参数解释与哈希、数据时点与质量状态、每条查询的执行/attempt/工件/来源证据引用。 + + 这是**交互入口**:`version` 点名就固定到它、不点名就读推荐版并当场固定(解析只发生一次);用途固定成 compose + (探索运行),不继承正式身份、也不拿它绕过 K07 的 formal 判定——要正式身份的是 K10 父 Run 的宿主入口 + (`querycore.execute_formal`,同一套 judge)。发布清单必须读得出来、就是这一版这一张图、约定与现在兼容;老资产 + (没有清单)明确拒。参数在发 SQL 之前就判完整性(缺参数/未声明/承载不了回 422,一条 SQL 都不发);最多等 30 秒, + 没跑完回 `status="running"` + run_id,**超时不算成功**。""" + from app.api.deps import current_principal + from app.ledger import querycore + + principal = current_principal() + try: + outcome = await querycore.execute(session, workflow_id=payload.workflow_id, card_id=payload.card_id, + metric_ids=payload.metric_ids, inputs=payload.inputs, + version=payload.version, actor=principal.username, + budget=payload.budget, trace=payload.trace) + except querycore.QueryCoreRefused as e: + raise CodedHTTPException(e.status_code, e.message, e.code, + extra=({"problems": [dict(p) for p in e.problems]} if e.problems else None) + ) from None + return outcome.as_dict() + + +# -------------------------------------------------------------------------- +# 受限的自然语言修改与固定请求路由(app/ledger/nlchange.py,K12) +# +# 自然语言只产出**一份 K03 提案**:operations + 影响摘要 + 澄清项,不落库、不新增版本,也没有第二条写路径。 +# confirm=true 时才按同一批操作落一版,走的仍是现有变更服务(patch_draft 那条路:expected_revision / request_id / +# CAS / 绑定同步 / 校验一条不少)。Ask Data 的确定请求直接进 QueryCore,路由只把版本固定一次,不重复解析/规划。 +# -------------------------------------------------------------------------- + + +class NlChangeIn(BaseModel): + """一句话 + 目标卡:默认只产出一份受限修改提案(confirm=false);confirm=true 时按同一批操作落一版。""" + + instruction: str = Field(min_length=1, max_length=2000) + #: 改哪张卡(图上有好几张可写的卡时必须给,不给则按草稿的权威卡) + target: DraftTargetIn | None = None + #: 显式点名要改哪几条指标(不给则按这句话、或声明过这个字段的指标) + metrics: list[str] | None = None + #: confirm=true 落版时要带的两样(K02):读到的基准版本、幂等键 + expected_revision: int | None = Field(default=None, ge=1) + request_id: str | None = Field(default=None, min_length=1, max_length=64) + #: 客户端确认:false(缺省)只预览,不落版 + confirm: bool = False + + +async def _nl_proposal(session: AsyncSession, draft_id: str, payload: NlChangeIn) -> tuple[Any, Any, str, Any]: + """读草稿、定目标卡、跑一遍 nlchange.propose。交回 (draft, workflow, card_id, proposal)。""" + from app.ledger import changes as change_service + from app.ledger import nlchange + from app.ledger.repository import CaliberGone + + draft = await _draft_or_404(session, draft_id) + workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None + if not _doc_draft_workflow(workflow): + raise CodedHTTPException(409, "这份草稿还没接管到工作流上(没有可改的图):字段操作落不到图上," + "请先起草或接上一次运行", CHANGE_UNAVAILABLE) + card_id = _target_card(payload, workflow) + try: + proposal = nlchange.propose(workflow.graph or {}, str(card_id), payload.instruction, + metrics=payload.metrics) + except change_service.ChangeRefused as e: + extra = {key: value for key, value in (("operation", e.operation), ("path", e.path)) if value is not None} + raise CodedHTTPException(422, e.message, e.code, field="operations", extra=extra) from None + except CaliberGone: # 目标卡在这中间没了或者成了转抄卡:和字段变更那条路同一句话、同一个码 + raise CodedHTTPException(409, DRAFT_CARD_GONE, CARD_NOT_FOUND, field="target") from None + return draft, workflow, str(card_id), proposal + + +def _proposal_refusal(proposal: Any) -> CodedHTTPException: + """提案说不清(含糊业务条件、没匹配能力):回 409,把澄清项原样带上,不落任何东西。""" + from app.ledger import nlchange + + first = proposal.clarifications[0] if proposal.clarifications else None + code = (nlchange.PROPOSAL_AMBIGUOUS + if first is not None and first.kind == nlchange.KIND_AMBIGUOUS else nlchange.PROPOSAL_NONE) + message = first.question if first is not None else "这句话没有能按字段改的已声明能力" + return CodedHTTPException(409, message, code, + extra={"clarifications": [item.as_dict() for item in proposal.clarifications]}) + + +@router.post("/drafts/{draft_id}/change-proposal") +async def change_proposal(draft_id: str, payload: NlChangeIn, + session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """一句话 → 受限修改提案(app/ledger/nlchange.py,K12):**只读**,不落库、不新增版本。 + + 产出 K03 同一形状的 operations、这次的影响摘要(失效与绑定结论,由 changes.summary 在同一批操作上现算)和必须先 + 问清的澄清项。识别只认已声明的能力(统计时间口径、退款处理这类业务字段);「排除退款」这种说不清取哪个值的先澄清, + 一条操作都不产出,不替人猜、也不擅自改口径。真要用它,客户端把 operations 交给 + `PATCH /api/ledger/drafts/{id}`(要带 expected_revision / request_id / target)或 `POST …/nl-change`。""" + from app.api.deps import ensure_role + + ensure_role("builder") + draft, workflow, card_id, proposal = await _nl_proposal(session, draft_id, payload) + return {"draft_id": draft.id, "workflow_id": workflow.id, "revision": workflow.version, "card": card_id, + "proposal": proposal.as_dict()} + + +@router.post("/drafts/{draft_id}/nl-change") +async def nl_change(draft_id: str, payload: NlChangeIn, + session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """一句话改口径(K12):默认只预览(confirm=false);confirm=true 时按同一批操作落一版。 + + **只是一层薄适配**:真落版时把它翻成一次 `DraftPatchIn(operations=…)`,交给现有变更服务(patch_draft)——K02 的 + expected_revision / request_id / CAS、K03 的深拷贝与整批原子、K04 的绑定同步、校验一条都不少。说不清(含糊业务条件、 + 没匹配能力)回 409 并带上澄清项,**一条操作都不落**:失败不擅自改口径。""" + from app.api.deps import ensure_role + + ensure_role("builder") + draft, workflow, card_id, proposal = await _nl_proposal(session, draft_id, payload) + view = {"draft_id": draft.id, "workflow_id": workflow.id, "revision": workflow.version, "card": card_id, + "proposal": proposal.as_dict()} + if not payload.confirm: + # 默认不自动落版:只交回提案,客户端确认后带着它回来 + return {**view, "applied": False, "persisted": False} + if not proposal.ready: + raise _proposal_refusal(proposal) + patch = DraftPatchIn(operations=[DraftOperationIn(**op) for op in proposal.operations], + expected_revision=payload.expected_revision, request_id=payload.request_id, + target=payload.target) + return await patch_draft(draft_id, patch, session) + + +class FixedRequestIn(BaseModel): + """Ask Data 的固定请求(K12):口径身份 + 要算的指标 + 入口取值,可选一句业务条件。 + + 已经明确 workflow/card/metric_ids/inputs 的确定请求直接进 QueryCore;没有匹配口径就进探索、含糊业务条件先澄清、 + 业务条件和匹配到的口径对不上就明确说「先改口径」,绝不静默换计算规则。purpose / actor 由服务端定,请求体不收。""" + + workflow_id: str | None = None + card_id: str | None = None + metric_ids: list[str] | None = None + inputs: dict[str, Any] = Field(default_factory=dict) + version: int | None = None + #: 一句话里的业务条件(可选):识别到含糊条件先澄清,识别到和这一版算法对不上的条件就进探索 + instruction: str | None = None + + +@router.post("/ask") +async def ask_fixed(payload: FixedRequestIn, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """固定请求路由(K12):能确定的直接进 QueryCore,说不清/没匹配的进澄清或探索。 + + 路由只把版本固定一次并交给 QueryCore(点名就固定到它、不点名读推荐版并当场固定),QueryCore 不再另挑一次, + 执行路径内部 LLM 仍为 0。返回里 route.mode 是 querycore / clarify / explore:querycore 时另带 result + (querycore.execute 的结果),其余两种只交回 route(澄清项或为什么进探索),**不发起任何运行、不改任何口径**。""" + from app.api.deps import current_principal + from app.ledger import nlchange, querycore + + principal = current_principal() + routed = await nlchange.route(session, request=payload.model_dump(), purpose=querycore.DEFAULT_PURPOSE) + out: dict[str, Any] = {"route": routed.as_dict(), "result": None} + if routed.mode != nlchange.ROUTE_EXECUTE: + return out + request = {key: value for key, value in routed.request.items() if key != "purpose"} + try: + outcome = await querycore.execute( + session, purpose=str(routed.request.get("purpose") or querycore.DEFAULT_PURPOSE), + actor=principal.username, **request) + except querycore.QueryCoreRefused as e: + raise CodedHTTPException(e.status_code, e.message, e.code, + extra=({"problems": [dict(p) for p in e.problems]} if e.problems else None) + ) from None + out["result"] = outcome.as_dict() + return out + + # -------------------------------------------------------------------------- # 从业务文档起草口径(app/ledger/docdraft.py;attach 是 app/ledger/docattach.py) # -------------------------------------------------------------------------- @@ -421,20 +741,21 @@ def _trial_binding(version: int, graph: dict[str, Any], values: dict[str, Any]) def _doc_draft_workflow(workflow: Workflow | None) -> bool: - return workflow is not None and isinstance(workflow.origin, dict) and workflow.origin.get("kind") == "doc_draft" + """这份草稿是不是已经接管到工作流上了(文档起草建出来的口径卡):只有它对图写入要带基准版本(K02)。""" + from app.apps.versions import taken_over + + return taken_over(workflow) async def _trial_view(session: AsyncSession, trial: dict[str, Any], *, version: int, graph: dict[str, Any]) -> dict[str, Any]: """历史试跑只能证明当时的版本和输入;运行超时返回 running 后,读时从 Run 刷新终态。""" - from app.core.artifact_store import canonical_json, content_hash, execution_hash, graph_hash + from app.core.artifact_store import canonical_json, content_hash if not trial: return {} run = await session.get(Run, trial["run_id"]) if trial.get("run_id") else None - same_graph = (trial.get("execution_hash") == execution_hash(graph) if trial.get("execution_hash") - else trial.get("version") == version and trial.get("graph_hash") == graph_hash(graph)) - if (not same_graph + if (not _same_graph(trial, graph, version) or (run is not None and trial.get("inputs_hash") != content_hash(canonical_json(run.input or {})))): return {**trial, "status": "stale", "error": "口径已修改或试运行缺少版本记录,请重新试运行"} if trial.get("run_id") and run is None: @@ -444,7 +765,31 @@ async def _trial_view(session: AsyncSession, trial: dict[str, Any], *, version: return trial -async def _save_trial(draft_id: str, trial: dict[str, Any], *, replace: bool = False) -> bool: +def _same_graph(trial: Mapping[str, Any], graph: Mapping[str, Any], version: int) -> bool: + """这次试跑记下的图指纹是不是就是 graph 这一版:执行哈希优先(忽略布局),旧试跑按版本 + 图哈希认。""" + from app.core.artifact_store import execution_hash, graph_hash + + if not isinstance(graph, Mapping) or not graph: + return False + if trial.get("execution_hash"): + return trial.get("execution_hash") == execution_hash(dict(graph)) + return trial.get("version") == version and trial.get("graph_hash") == graph_hash(dict(graph)) + + +async def _save_trial(draft_id: str, trial: dict[str, Any], *, replace: bool = False, + expect: Mapping[str, Any] | None = None) -> bool: + """保存这一次试跑,并把它**追加**成一条验证记录(K05)。 + + 旧版本或较早的试跑晚结束时,不能覆盖新的验证结果——但**记录照旧追加**:新旧两次试跑都留得下(各自的定义和 + 绑定依据都记在记录里),读的时候按覆盖算谁对当前版本说话(见 _record_trial)。 + """ + ok = await _write_trial_pointer(draft_id, trial, replace=replace, expect=expect) + await _record_trial(draft_id, trial, expect=expect) + return ok + + +async def _write_trial_pointer(draft_id: str, trial: dict[str, Any], *, replace: bool = False, + expect: Mapping[str, Any] | None = None) -> bool: """旧版本或较早的试跑晚结束时,不能覆盖新的验证结果。""" async with SessionLocal() as fresh: row = await fresh.scalar(select(CaliberDraft).where(CaliberDraft.id == draft_id).with_for_update()) @@ -452,11 +797,7 @@ async def _save_trial(draft_id: str, trial: dict[str, Any], *, replace: bool = F return False workflow = await fresh.get(Workflow, row.workflow_id) if row.workflow_id else None if _doc_draft_workflow(workflow): - from app.core.artifact_store import execution_hash, graph_hash - - same_graph = (trial.get("execution_hash") == execution_hash(workflow.graph) if trial.get("execution_hash") - else trial.get("version") == workflow.version and trial.get("graph_hash") == graph_hash(workflow.graph)) - if not same_graph: + if not _same_graph(trial, workflow.graph or {}, workflow.version): return False body = dict(row.payload) current = body.get("trial") or {} @@ -465,6 +806,9 @@ async def _save_trial(draft_id: str, trial: dict[str, Any], *, replace: bool = F if not replace and current.get("run_id") and current.get("run_id") != trial.get("run_id"): return False body["trial"] = trial + if expect: + # 这次试跑的固定期望跟着 payload 存一份(按 trial_id 认):试跑超时、晚些才跑完时,读接口补记记录还用得上 + body[TRIAL_EXPECT_KEY] = {**dict(expect), "trial_id": str(trial.get("trial_id") or "")} # SQLite 忽略 FOR UPDATE;加上读时的修订时间,避免并发完成或编辑覆盖刚写入的新内容。 from sqlalchemy import update @@ -478,6 +822,254 @@ async def _save_trial(draft_id: str, trial: dict[str, Any], *, replace: bool = F return True +#: payload 里放「这次试跑的固定期望」的键(按 trial_id 认):试跑超时、晚些才跑完时,读接口补记记录还用得上 +TRIAL_EXPECT_KEY = "trial_expectation" + + +def _record_status(status: Any) -> str | None: + """试跑状态 → 值得记一条验证记录的状态;还在跑(running / 空)时返回 None。""" + text = str(status or "") + return text if text in ("succeeded", "failed", "needs_input", "stale") else None + + +def _has_stable_trial_key(trial: Mapping[str, Any]) -> bool: + """这次试运行有没有服务端给的稳定身份(trial_id,或老写法的 run_id)。""" + trial = trial or {} + return bool(str(trial.get("trial_id") or "") or str(trial.get("run_id") or "")) + + +def _stable_trial_key(trial: Mapping[str, Any]) -> str: + """这次试运行在验证记录里的身份:trial_id 优先,老写法退到 run_id。 + + 两样都没有时给一个**由这次试运行本身推出来的确定键**(版本 + 图指纹 + 输入指纹 + 状态 + 错误),不是随机 id: + 同一份 trial 反复保存落到同一行,快照/读取也不会一次多出一行。新试运行都带 trial_id(_run_trial 建 binding 时写, + authoring.extract 的失败分支同样写),这个兜底只给历史数据和不走 _run_trial 的调用方用。 + """ + trial = trial or {} + for key in ("trial_id", "run_id"): + value = str(trial.get(key) or "") + if value: + return value + from app.core.artifact_store import canonical_json, content_hash + + digest = content_hash(canonical_json({ + "version": trial.get("version"), "graph_hash": str(trial.get("graph_hash") or ""), + "execution_hash": str(trial.get("execution_hash") or ""), + "inputs_hash": str(trial.get("inputs_hash") or ""), + "status": str(trial.get("status") or ""), "error": str(trial.get("error") or "")})) + return f"derived-{digest[:24]}" + + +async def _resolve_trial_graph(session: AsyncSession, workflow: Workflow | None, trial: Mapping[str, Any] + ) -> dict[str, Any]: + """这次试跑对着的那张图:当前图就是它就用当前图;不是(晚结束的旧试跑)就到这一工作流的版本里按图指纹找。 + + 都找不到时交回空图:记录照旧追加(这次试跑确实发生过),但依据留空、covers_current 一律 False——不拿当前 + 定义冒充它当时跑的那一份。 + """ + from app.core.artifact_store import execution_hash, graph_hash + + current = workflow.graph if workflow is not None and isinstance(workflow.graph, dict) else {} + if current and _same_graph(trial, current, workflow.version): + return current + if workflow is None: + return {} + rows = (await session.execute(select(WorkflowVersion).where( + WorkflowVersion.workflow_id == workflow.id))).scalars() + wanted = str(trial.get("execution_hash") or "") + digest = str(trial.get("graph_hash") or "") + for row in rows: + graph = row.graph if isinstance(row.graph, dict) else None + if not graph: + continue + if wanted and execution_hash(graph) == wanted: + return graph + if not wanted and digest and graph_hash(graph) == digest: + return graph + return {} + + +async def _trial_metric_links(run_id: str) -> tuple[dict[str, str], list[dict[str, Any]]]: + """这次运行的**指标 → 取数快照**的可靠关联(判形状用),以及每份快照的行数。 + + 指标记录本身不带取数节点(_trial_metrics 给界面看的那几个字段里没有),但封存的口径卡里有:每个指标的 + `inputs` 记着它取自哪份查询快照(`origin.artifact` / `query_artifact` / `artifact`,和引擎判 contract_findings + 时同一套认法),认不出工件时退回它记下的取数节点。返回 + `(metric_id → 查询快照的键, [{key, node_id, total_rows, truncated}])`。 + + **不放进给用户看的响应**:这一份只喂给验证记录(app/ledger/validation.actual_of),响应里的指标键一个不变。 + 读不出封存证据时给空(照实记「形状判不了」→ unverified),不猜。 + """ + from app.core.artifact_store import load + from app.engine.evidence_reader import metric_cards, read_sealed + + try: + sealed = await read_sealed(run_id) + if not sealed.trusted: + return {}, [] + except Exception: # noqa: BLE001 - 证据读不出来只影响形状判断,记录照落 + logger.exception("试运行 %s 的封存证据读不出来,验证记录按「形状判不了」记", run_id) + return {}, [] + snapshots: list[dict[str, Any]] = [] + artifacts: set[str] = set() + for artifact, info in (sealed.queries or {}).items(): + try: + snap = load(artifact) + except Exception: # noqa: BLE001 - 这一份读不出来就跳过它(还有别的快照) + logger.warning("试运行 %s 的查询快照 %s 读不出来", run_id, artifact, exc_info=True) + continue + if not isinstance(snap, dict) or not isinstance(snap.get("rows"), list): + continue + artifacts.add(str(artifact)) + snapshots.append({"key": str(artifact), "node_id": str((info or {}).get("node_id") or ""), + "total_rows": len(snap["rows"]), "truncated": bool(snap.get("truncated"))}) + links: dict[str, str] = {} + try: + for _card_node, _card_artifact, card in metric_cards(sealed): + for metric in card.get("metrics") or []: + if not isinstance(metric, Mapping) or not metric.get("id"): + continue + key = _metric_query_key(metric, artifacts) + if key: + links.setdefault(str(metric["id"]), key) + except Exception: # noqa: BLE001 - 认不出关联时按判不了记,不让它把记录弄没 + logger.warning("试运行 %s 的指标与查询快照关联认不出来", run_id, exc_info=True) + return links, snapshots + + +def _metric_query_key(metric: Mapping[str, Any], artifacts: set[str]) -> str: + """这条指标读的是哪份查询快照:输入里认得出工件就用工件 id,认不出就退回它记下的取数节点。""" + inputs = [item for item in metric.get("inputs") or [] if isinstance(item, Mapping)] + for item in inputs: + for candidate in ((item.get("origin") or {}).get("artifact") if isinstance(item.get("origin"), Mapping) + else None, item.get("query_artifact"), item.get("artifact")): + if isinstance(candidate, str) and candidate and (not artifacts or candidate in artifacts): + return candidate + return next((str(item["node_id"]) for item in inputs if item.get("node_id")), "") + + +async def _record_trial(draft_id: str, trial: Mapping[str, Any], *, expect: Mapping[str, Any] | None = None, + origin: str = "trial") -> str | None: + """把一次试跑追加成一条验证记录(K05)。晚结束的旧试跑也照记:指针可能不换,记录一定留。 + + 记的是这一件事:这次在**哪一份定义和绑定**上(卡、定义指纹、绑定指纹、取数语义指纹)、拿什么输入、和什么 + 独立期望比、实际是什么、结论是什么。没有独立期望时只记 observed——不能算验证通过。 + """ + from app.ledger import validation + + status = _record_status(trial.get("status")) + if status is None: + return None + run_id = str(trial.get("run_id") or "") + # 这一次试运行的身份:trial_id 优先,老写法退到 run_id,两样都没有时按这次试运行的内容推一个确定键 + # (见 _stable_trial_key)——同一份 trial 反复保存只落一行,晚到的旧试运行也不会被当成另一次 + record_key = _stable_trial_key(trial) + inputs: dict[str, Any] = {} + actor: str | None = None + recorded_metrics: list[dict[str, Any]] = [] + snapshots: list[dict[str, Any]] = [] + links: dict[str, str] = {} + problems: list[str] = [] + async with SessionLocal() as session: + draft = await session.get(CaliberDraft, draft_id) + if draft is None or not isinstance(draft.payload, dict): + return None + workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None + graph = await _resolve_trial_graph(session, workflow, trial) + resolved_card, cards = draft_card(graph) if graph else (None, []) + card_id = str(resolved_card or (cards[0]["id"] if cards else "") or "") + card_metrics = validation.card_metrics(graph, card_id) if card_id else [] + metric_ids = [str(metric["id"]) for metric in card_metrics] + materials = (validation.materials(graph, card_id, workflow_id=str(draft.workflow_id or "")) + if graph and card_id else + {"workflow_id": str(draft.workflow_id or ""), "card_id": "", "definition_hash": "", + "binding_fingerprints": {}, "semantic_hash": ""}) + if not materials["definition_hash"]: + problems.append("这次试运行找不到对应的定义版本:这条记录只作追踪,不能算覆盖任何一版定义") + if status == "succeeded" and run_id: + run = await session.get(Run, run_id) + inputs = dict(run.input or {}) if run is not None and isinstance(run.input, dict) else {} + actor = getattr(run, "started_by", None) if run is not None else None + try: + recorded_metrics = await _trial_metrics(run_id) + # 指标 → 取数快照的关联从封存的口径卡里认(指标记录本身不带节点):不认这一份,真实运行的形状 + # 一律判不了,matched 就永远到不了。这一份不进给用户看的响应。 + links, snapshots = await _trial_metric_links(run_id) + except Exception: # noqa: BLE001 - 结果读不出来照实记「没有可比较的实际值」,不让它把记录弄没 + logger.exception("试运行 %s 的结果读不出来,验证记录按「没有可比较的实际值」记", run_id) + recorded_metrics, snapshots, links = [], [], {} + elif run_id: + # 没跑成、停在 needs_input 这类:没有可比较的实际值,但「这次拿什么输入去跑」照记 + run = await session.get(Run, run_id) + inputs = dict(run.input or {}) if run is not None and isinstance(run.input, dict) else {} + actor = getattr(run, "started_by", None) if run is not None else None + stored = draft.payload.get(TRIAL_EXPECT_KEY) + wanted = expect if expect else ( + stored if isinstance(stored, Mapping) + and str(stored.get("trial_id") or "") == str(trial.get("trial_id") or "") else None) + expectation = validation.expectation_of(wanted, card_metrics_=card_metrics) + actual = validation.actual_of(metrics=recorded_metrics, queries=snapshots, card_metrics_=card_metrics, + metric_ids=metric_ids, links=links) + result = validation.compare(expected=(expectation or {}).get("metrics") if expectation else None, + actual=actual, metric_ids=metric_ids, card_metrics_=card_metrics, + run_status=("succeeded" if status == "succeeded" + else "failed" if status == "failed" else "skipped"), + problems=problems) + from app.core.artifact_store import execution_hash + + return await validation.append( + draft_id=draft_id, workflow_id=str(materials.get("workflow_id") or "") or None, + version=int(trial.get("version") or 1), card_id=str(materials.get("card_id") or ""), + metric_ids=metric_ids, basis=materials, inputs=inputs, inputs_hash=str(trial.get("inputs_hash") or ""), + trial_id=record_key, run_id=run_id, actor=actor, status=result["status"], + problems=result["problems"], expectation=expectation, actual=result["actual"], + execution_hash=str(trial.get("execution_hash") or "") + or (execution_hash(graph) if graph else ""), origin=origin) + + +async def _ensure_trial_records(draft: CaliberDraft, trial: Mapping[str, Any], *, origin: str = "late" + ) -> str | None: + """读的时候把已经到终态、还没有记录的试运行补记一条(超时后晚完成的那些,以及过期成 stale 的那些)。 + + **只对有稳定身份(trial_id / run_id)的试运行追加**:老草稿 payload 里留下的那一条没有身份,认不出「是不是 + 同一次」(补记一次、读十次就会多出十行),只读不改。记录按 (草稿, 身份, 状态) 去重;还在执行的什么都不做。 + """ + if _record_status((trial or {}).get("status")) is None or not _has_stable_trial_key(trial): + return None + return await _record_trial(draft.id, trial, origin=origin) + + +async def _trial_record(session: AsyncSession, draft_id: str, trial: Mapping[str, Any]) -> Any: + """这次试运行对应的那条验证记录;没有就是 None。 + + **不退回「最新的一条」**:那可能是另一次试运行的记录,拿它冒充本次记录会让页面显示错的依据。 + """ + from app.ledger import validation + + if _record_status((trial or {}).get("status")) is None: + return None + return await validation.find_record(session, draft_id, _stable_trial_key(trial)) + + +async def _trial_record_brief(session: AsyncSession, record: Any, *, + current: Mapping[str, Any] | None) -> dict[str, Any]: + """试运行响应里的那一段:本次试运行的验证记录 + 覆盖判断(**每个分支形状都一样**)。 + + covers_current 是三态:True(还覆盖当前定义/绑定)、False(不覆盖)、None(这次没有可判的记录——还在执行, + 或没有稳定身份,或没有交回记录)。没有记录时也明说一句,不给一个空对象让人猜,也不拿别的记录顶上。 + """ + from app.ledger import review, validation + + if record is None: + return {"record": None, "covers_current": None, + "note": "这次试运行还没有留下可对应的验证记录:不能算验证通过"} + reviews = await review.latest_by_record(session, [record.id], current=current) + made = validation.as_dict(record, current=current, review=reviews.get(record.id)) + return {"record": made, "covers_current": made["covers_current"], + "note": "这次试运行的结果只说明这一次执行成什么样;它还算不算覆盖当前的定义与绑定," + "看下面「是否覆盖当前版本」这一项"} + + async def _run_trial(*, draft_id: str, workflow_id: str, graph: dict[str, Any], values: dict[str, Any], started_by: str | None, version: int = 1, entry_fields: list[dict[str, Any]] | tuple[dict[str, Any], ...] = ()) -> dict[str, Any]: @@ -523,6 +1115,13 @@ async def _run_trial(*, draft_id: str, workflow_id: str, graph: dict[str, Any], target = caliber_probe(pinned).graph except NotDerivable as e: return await failed("failed", f"口径卡不能派生探针:{e.message}") + # 参数完整性(ledger/params,和 trial_caliber、组合式问数同一套):模板里的参数这次没有值(可选、没有缺省值的 + # 也算缺)、引用的字段入口没声明、值承载不了——都在发起运行之前停住,一条 SQL 都不发 + from app.ledger import params + + if problems := params.check_nodes(pinned.fetches, fields=pinned.entry_fields, values=values, + where=f"口径「{pinned.workflow_name}」的入口"): + return await failed("needs_input", params.describe(problems)) try: run = await run_manager.start( @@ -655,15 +1254,14 @@ async def _trial_queries(run_id: str) -> list[dict[str, Any]]: def _draft_summary(draft: CaliberDraft, *, graph: dict[str, Any] | None = None) -> dict[str, Any]: """列表和详情共用的一份摘要:细状态照实给,另给界面用的四阶段 stage。""" + from app.apps.tree import node_map from app.ledger import docdraft payload = draft.payload if isinstance(draft.payload, dict) else {} if graph is not None: - from app.apps.tree import node_map - - card = next((node for node in node_map(graph).values() if node.get("type") == "metrics" - and not (node.get("config") or {}).get("caliber_from")), None) - payload = {**payload, "metrics": ((card or {}).get("config") or {}).get("metrics") or []} + card_id, cards = draft_card(graph) + card = node_map(graph).get(card_id or (cards[0]["id"] if cards else "")) or {} + payload = {**payload, "metrics": (card.get("config") or {}).get("metrics") or []} metrics = payload.get("metrics") return {"id": draft.id, "title": draft.title, "status": draft.status, "stage": docdraft.stage_of(draft.status), @@ -672,26 +1270,71 @@ def _draft_summary(draft: CaliberDraft, *, graph: dict[str, Any] | None = None) "created_at": draft.created_at.isoformat() if draft.created_at else None, "error": draft.error} -async def _draft_view(session: AsyncSession, draft: CaliberDraft) -> dict[str, Any]: +async def _draft_view(session: AsyncSession, draft: CaliberDraft, *, ensure_records: bool = False + ) -> dict[str, Any]: """一份草稿的完整样子:payload 摊平在上层(界面直接读 metrics / open_questions),另加状态和关联工作流名。 - 文档起草建了工作流和 v1 之后,图是唯一真相:画布上改过指标或取数 SQL,这里从图里取最新的那几项覆盖 payload - 里的起草快照。接上一次运行(docattach)的草稿仍看 payload。 + 接管到工作流上的(文档起草建出来的、以及接上一次运行的 docattach 产物)图是唯一真相:画布上改过指标或取数 + SQL,这里从图里取最新的那几项覆盖 payload 里的起草快照。两类都按 taken_over 认(见 app/apps/versions.py), + 所以 docattach 的产物也是从图里读,不退回它接上那一刻的快照。 + + 另给写入要用的两样(K02):card_id 是这份草稿的权威口径卡,revision 是客户端要带回来的基准版本 + (Workflow.version);没有接管到工作流上的老草稿两样都是 None(照旧只改 payload)。 + + 来源基线(K05 的读取侧)现算现给,而且**会把快照工件真的读一遍**(load 复验哈希):读得回来才是 known,没有 + 这份引用(保存快照之前起草的老草稿、这次落库失败)或工件不在/被改过都是 baseline_unknown(readable=false, + 带上那个工件 id 和原因)。老草稿也照样给这一段——「不知道基线是什么」本身就是要说的话,比不写更安全;反过来, + payload 里存过的状态不作数,工件坏了就是坏了,读草稿不会因此抛错。不另补、不伪造 B。 + + 字段基线 B(K05)另给一段 field_baseline:首次接受导入时按 metric_id + field_path 存下的那件工件(值是值、 + 引用是引用,逐格带哈希),状态只有 known / baseline_unknown,另带 readable(工件读不读得回来)。人工改过 L 之后 + 这一段不变——B 说的是「上次被接受的导入值」,不是「现在长什么样」;工件被删或被改过时照实说 baseline_unknown + (readable=false),不报成 known,也不把读草稿抛崩。 + + 验证总情况另给一段 validation(K05):covers_current(现有记录还覆不覆盖当前定义/绑定)、最新一条的状态、 + 审阅结论和计数。verdict 才是结论:没有记录是 none、都不覆盖是 stale、只有独立期望对得上**并且**有认证审阅确认了 + 这份记录**全部**指标才是 verified(confirmed / unconfirmed 分别列出确认到和还没确认的指标)。整条记录 + (期望/实际/问题/审阅)走 GET /api/ledger/drafts/{id}/validations。 + + 已接管的草稿另给 binding(K04 的服务端能力描述):能按字段改的业务定义、允许值、现在的值、定义和取数实现的 + 同步状态(aligned / needs_update / unsupported / unbound)、不支持时的原因和该做什么——工作台照它决定展示哪些 + 业务修改。aligned 只说定义和实现同步,不等于验证通过。 """ + from app.ledger import docdraft, fieldbaseline + payload = draft.payload if isinstance(draft.payload, dict) else {} workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None + taken_over = _doc_draft_workflow(workflow) + card_id, cards = draft_card(workflow.graph or {}) if taken_over else (None, []) view = {**payload, **_draft_summary(draft), "collection": draft.collection, "datasource_id": draft.datasource_id, "origin": draft.origin if isinstance(draft.origin, dict) else {}, "model_id": draft.model_id or payload.get("model_id"), "created_by": draft.created_by, "updated_at": draft.updated_at.isoformat() if draft.updated_at else None, + "card_id": card_id, "cards": cards, "revision": workflow.version if taken_over else None, "workflow_name": workflow.name if workflow is not None else None} - if _doc_draft_workflow(workflow): + # 来源基线现算现给(不拿 payload 里存过的那份):有可还原的快照才是 known,快照被删被改照实说 baseline_unknown + # (readable=false)。老草稿没有这份引用,同样如实标 unknown,不拿它现在的内容冒充「上次被接受的导入值」。 + view["source_baseline"] = docdraft.source_baseline(payload) + if taken_over: + # 这张卡上的业务绑定(K04):能按字段改什么、允许哪些值、定义和取数实现现在同步到哪一步 + from app.ledger import bindings + + view["binding"] = bindings.capability(workflow.graph or {}, str(card_id)) + if taken_over: live = await _draft_graph_payload(session, workflow, workflow.version, draft=draft, payload=payload) if live is not None: view.update(live) view["metric_count"] = len(live["metrics"]) view["question_count"] = _question_count(view) + # K05 的两段:字段基线 B 的状态(这次导入被接受成什么、有没有),以及验证总情况(有没有覆盖当前版本的记录、 + # 最新一条、审阅结论)。两段都现算现给:B 不因为人工改过 L 而变,覆盖也不因为旧记录还在就成立。 + if ensure_records: + # 已经到终态、还没记过的试跑(超时后晚完成的那些)补记一条。只在纯读的入口做(GET 草稿 / 试跑 / + # 验证列表):写路径上这会和请求自己的写事务抢锁。 + await _ensure_trial_records(draft, view.get("trial") or {}) + view["field_baseline"] = fieldbaseline.status_of(payload) + view["validation"] = await _draft_validation_summary(session, draft, workflow=workflow) from app.db.models import CaliberDraftJob job = await session.get(CaliberDraftJob, draft.id) @@ -702,6 +1345,43 @@ async def _draft_view(session: AsyncSession, draft: CaliberDraft) -> dict[str, A return view +def _current_materials(workflow: Workflow | None) -> dict[str, Any] | None: + """这份草稿**当前**的定义/绑定依据(覆盖判断拿它和记录里的依据比)。读不到图或认不出卡时给 None。 + + 三样指纹——定义(definition_hash)、绑定(binding_fingerprints)、取数语义(semantic_hash,含 SQL 和数据源)—— + 就是「这一版是什么」。布局变更不在里面,所以移动画布不作废验证(4.1)。 + """ + from app.ledger import validation + + graph = workflow.graph if _doc_draft_workflow(workflow) and isinstance(workflow.graph, dict) else None + if not graph: + return None + card_id, cards = draft_card(graph) + card_id = str(card_id or (cards[0]["id"] if cards else "") or "") + if not card_id: + return None + return validation.materials(graph, card_id, workflow_id=str(getattr(workflow, "id", "") or "")) + + +async def _draft_records(session: AsyncSession, draft: CaliberDraft, *, workflow: Workflow | None = None + ) -> dict[str, Any]: + """这份草稿的验证记录(新的在前)+ 总情况:列表接口和详情共用同一份读法。""" + from app.ledger import review, validation + + rows = await validation.list_for_draft(session, draft.id) + current = _current_materials(workflow) + reviews = await review.latest_by_record(session, [row.id for row in rows], current=current) + return {"records": [validation.as_dict(row, current=current, review=reviews.get(row.id)) for row in rows], + "summary": validation.summarize(rows, current=current, reviews=reviews), + "method": {"version": validation.METHOD_VERSION, "note": validation.METHOD_NOTE}} + + +async def _draft_validation_summary(session: AsyncSession, draft: CaliberDraft, *, + workflow: Workflow | None = None) -> dict[str, Any]: + """草稿详情里那一段「验证总情况」:覆盖判断、最新一条记录、审阅结论(记录本身走验证列表接口)。""" + return (await _draft_records(session, draft, workflow=workflow))["summary"] + + def _graph_entry_fields(graph: dict[str, Any]) -> list[dict[str, Any]]: """图里入口节点(input)的字段;草稿页和试跑用它,画布改过的入口字段不会被 payload 的旧快照盖住。""" from app.apps.tree import node_map @@ -810,12 +1490,15 @@ async def _draft_checks(session: AsyncSession, draft: CaliberDraft, payload: dic async def _draft_graph_payload(session: AsyncSession, workflow: Workflow, version: int, *, draft: CaliberDraft | None = None, - payload: dict[str, Any] | None = None) -> dict[str, Any] | None: + payload: dict[str, Any] | None = None, + card_id: str | None = None) -> dict[str, Any] | None: """从草稿工作流的某一版图里取出草稿页要显示的那几项(指标、入口、SQL、groups)。 图是唯一真相:画布上改了指标名、定义或取数 SQL,草稿页跟着图变,不显示 payload 里起草那一刻的快照。取数节点 按 SQL 分组,指标按表达式里引用的节点归组;表达式不引用取数节点的(比如只读 vars)归到第一组。图里没有口径卡 或没有指标时交回空指标列表,不能退回起草时的旧快照。 + + card_id 是这次要读的那张口径卡(写入时由 target.card_id 定);不给就按这张草稿的权威卡(draft_card)。 """ from app.apps.tree import node_map @@ -825,9 +1508,10 @@ async def _draft_graph_payload(session: AsyncSession, workflow: Workflow, versio if row is None or not isinstance(row.graph, dict): return None nodes = node_map(row.graph) - card = next((node for node in nodes.values() - if node.get("type") == "metrics" - and not (node.get("config") or {}).get("caliber_from")), None) + wanted, cards = draft_card(row.graph) + # 读的时候认不出唯一的权威卡(多张、契约也没说是哪张)就照旧显示第一张:显示不改任何东西,写入那条路上会拒 + wanted = card_id or wanted or (cards[0]["id"] if cards else None) + card = nodes.get(wanted) if wanted else None metrics = [metric for metric in ((card or {}).get("config") or {}).get("metrics") or [] if isinstance(metric, dict) and metric.get("id")] fields = _graph_entry_fields(row.graph) @@ -874,6 +1558,172 @@ async def _draft_or_404(session: AsyncSession, draft_id: str) -> CaliberDraft: return draft +# -------------------------------------------------------------------------- +# 卡级身份与写入保护(K02):卡是明确的,不按「第一张」猜;写要带基准版本和幂等键 +# -------------------------------------------------------------------------- + +#: 卡级定位与幂等冲突的机器码(STALE_REVISION / REVISION_REQUIRED 在 apps/versions.py,和这里一起构成 K02 的契约) +CARD_REQUIRED = "card_required" +CARD_NOT_FOUND = "card_not_found" +TARGET_MISMATCH = "target_mismatch" +IDEMPOTENCY_CONFLICT = "idempotency_conflict" +#: 字段变更(K03)的机器码:同一次请求里既整份换指标、消问题,又按字段改(一次请求只落一版图);这份草稿还没有图 +CHANGE_CONFLICT = "change_conflict" +CHANGE_UNAVAILABLE = "change_unavailable" +#: 草稿改完之后对不上目标卡 +DRAFT_CARD_GONE = "这份草稿的口径卡不见了(可能刚被删掉):请刷新页面再看一次" + + +def editable_cards(graph: dict[str, Any]) -> list[dict[str, str]]: + """图里能写的一张张口径卡:[{id, title}],按节点出现的顺序。 + + 能写的是源头口径卡(metrics 节点、没有 caliber_from):转抄别处的口径卡不是权威写入源(A01),改它等于在别处 + 另存一份定义。 + """ + from app.apps.tree import node_map + + return [{"id": node_id, "title": str(node.get("title") or node_id)} + for node_id, node in node_map(graph).items() + if node.get("type") == "metrics" and not (node.get("config") or {}).get("caliber_from")] + + +def contract_card(graph: dict[str, Any]) -> str | None: + """下游契约声明从哪张卡取指标(metrics_from 只写了一张时就是它):多张卡时按它认这张草稿的权威卡。""" + for node in graph.get("nodes") or []: + config = ((node or {}).get("data") or {}).get("config") if isinstance(node, dict) else None + contract = config.get("contract") if isinstance(config, dict) else None + if not isinstance(contract, dict): + continue + sources = contract.get("metrics_from") + ids = [sources] if isinstance(sources, str) else [s for s in sources or [] if isinstance(s, str)] + if len(ids) == 1: + return ids[0] + return None + + +def draft_card(graph: dict[str, Any]) -> tuple[str | None, list[dict[str, str]]]: + """这份草稿的权威口径卡,另交回全部能写的卡。 + + 一张能写的卡时就是它;多张时认下游契约声明的那一张——不是「第一张」。都认不出来时交回 None:写的时候必须显式 + 给 target.card_id,读的时候页面也照实列候选。 + """ + cards = editable_cards(graph) + if len(cards) == 1: + return cards[0]["id"], cards + referenced = contract_card(graph) + if referenced and any(card["id"] == referenced for card in cards): + return referenced, cards + return None, cards + + +def _target_card(payload: "DraftPatchIn", workflow: Workflow) -> str | None: + """这次 PATCH 写哪张卡:给了 target.card_id 就按它(必须在图上、是可写的那种),没给就按这张草稿的权威卡。 + + target.workflow_id 只要给了就必须是这份草稿自己的——不符就回 409 target_mismatch,**没给 card_id 也一样**: + 指到别的工作流上,后面按卡定位的那几步就成了「拿着另一个工作流的名字在本图的卡里找」,先点破比按 id 撞库好。 + 多张可写的卡又没写明显式目标时拒(409 card_required),不做「取第一张」;指到的卡不在图上(或者指到了转抄卡) + 拒(409 card_not_found)。 + """ + target = payload.target + if target is not None and target.workflow_id and target.workflow_id != workflow.id: + raise CodedHTTPException(409, f"要改的口径卡不在这份草稿的工作流上(现在这份是「{workflow.name}」)", + TARGET_MISMATCH, field="target") + cards = editable_cards(workflow.graph or {}) + wanted = target.card_id if target is not None else None + if wanted: + if not any(card["id"] == wanted for card in cards): + raise CodedHTTPException( + 409, f"图上没有这张可写的口径卡:{wanted}。可写的卡是源头口径卡(转抄别处的口径卡不能在这里改)", + CARD_NOT_FOUND, field="target") + return wanted + if len(cards) == 1: + return cards[0]["id"] + if not cards: + raise CodedHTTPException(409, "当前画布没有可编辑的口径卡,请先在画布上添加", CARD_NOT_FOUND) + raise CodedHTTPException(409, "这张草稿的图上有好几张可写的口径卡:请指明要改哪一张(target.card_id)", + CARD_REQUIRED, field="target", extra={"cards": cards}) + + +async def _sync_draft_graph(session: AsyncSession, draft: CaliberDraft, payload_data: dict[str, Any], + *, card_id: str, expected_revision: int | None) -> None: + """在当前图上修改这一张口径卡,再新增版本;取数节点、SQL、入口和用户添加的编排保持其身份。""" + from app.apps.versions import STALE_REVISION, WorkflowChanged, save_graph + + workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None + metrics = payload_data.get("metrics") + if not _doc_draft_workflow(workflow) or not isinstance(metrics, list): + return + graph = copy.deepcopy(workflow.graph) + card = next((n for n in graph.get("nodes") or [] if isinstance(n, dict) and n.get("id") == card_id), None) + if card is None or card.get("type") != "metrics" or (card.get("data", {}).get("config") or {}).get("caliber_from"): + raise CodedHTTPException(409, DRAFT_CARD_GONE, CARD_NOT_FOUND) + config = card.setdefault("data", {}).setdefault("config", {}) + old_ids = {m.get("id") for m in config.get("metrics") or [] if isinstance(m, dict)} + new_ids = [m.get("id") for m in metrics] + if any(not isinstance(mid, str) or not mid.strip() for mid in new_ids) or len(set(new_ids)) != len(new_ids): + raise ValueError("每条指标需要非空且唯一的 ID") + config["metrics"] = copy.deepcopy(metrics) + removed = old_ids - set(new_ids) + for node in graph.get("nodes") or []: + contract = node.get("data", {}).get("config", {}).get("contract") + if not isinstance(contract, dict): + continue + sources = contract.get("metrics_from") or [] + if card_id not in ([sources] if isinstance(sources, str) else sources): + continue + for key in ("required", "expected"): + if isinstance(contract.get(key), list): + before = contract[key] + contract[key] = list(new_ids) if key == "required" and set(before) == old_ids \ + else [mid for mid in before if mid not in removed] + try: + await save_graph(session, workflow, graph, note="编辑口径草稿", expected_revision=expected_revision) + except WorkflowChanged as e: + raise CodedHTTPException(409, str(e), STALE_REVISION, + extra={"current_version": getattr(e, "current", workflow.version)}) from None + await session.flush() + live = await _draft_graph_payload(session, workflow, workflow.version, card_id=card_id) + if live is not None: + payload_data.update(live) + + +async def _sync_draft_changes(session: AsyncSession, draft: CaliberDraft, payload_data: dict[str, Any], *, + card_id: str, expected_revision: int | None, + operations: list["DraftOperationIn"]) -> "changes.Change": + """按字段操作改这一张口径卡,再新增版本(K03):改在**原图的深拷贝**上,没提到的内容原样带着走。 + + 和整份换指标那条路同一条并发规矩(K02 的 CAS:expected_revision 对不上或者别人先提交了,回 409 stale_revision)。 + 整批操作先在拷贝上跑完:任何一条不合规、或者指不到指标,都在写之前停住——图一个字节都不动,也不新增版本。 + """ + from app.apps.versions import STALE_REVISION, WorkflowChanged, save_graph + from app.ledger import changes + from app.ledger.repository import CaliberGone + + workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None + if not _doc_draft_workflow(workflow): + raise CodedHTTPException(409, "这份草稿还没接管到工作流上(没有可改的图):字段操作落不到图上," + "请先起草或接上一次运行", CHANGE_UNAVAILABLE) + try: + change = changes.apply_operations(workflow.graph or {}, card_id=str(card_id), + operations=[op.model_dump(exclude_unset=True) for op in operations]) + except changes.ChangeRefused as e: + extra = {key: value for key, value in (("operation", e.operation), ("path", e.path)) if value is not None} + raise CodedHTTPException(422, e.message, e.code, field="operations", extra=extra) from None + except CaliberGone: # 目标卡在这中间没了或者成了转抄卡:和整份换指标那条路同一句话、同一个码 + raise CodedHTTPException(409, DRAFT_CARD_GONE, CARD_NOT_FOUND, + field="target") from None + try: + await save_graph(session, workflow, change.graph, note="改口径字段", expected_revision=expected_revision) + except WorkflowChanged as e: + raise CodedHTTPException(409, str(e), STALE_REVISION, + extra={"current_version": getattr(e, "current", workflow.version)}) from None + await session.flush() + live = await _draft_graph_payload(session, workflow, workflow.version, card_id=card_id) + if live is not None: + payload_data.update(live) + return change + + def _doc_title(docs: list[Document]) -> str: """草稿标题取第一份文档的名字;多份文档写明还有几份。""" first = docs[0] @@ -1000,11 +1850,12 @@ async def list_drafts(status: str | None = Query(default=None, description="按 @router.get("/drafts/{draft_id}") async def get_draft(draft_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: """一份草稿的完整内容:指标(含引用和 span)、取数 SQL、入口字段、试跑状态、丢弃原因、未决问题、和已发布口径的对齐 - 结果、关联工作流名。""" + 结果、关联工作流名;另给 K05 的两段:字段基线 B 的状态(field_baseline)和验证总情况(validation:覆盖判断、 + 最新一条记录、审阅结论——记录本身走 GET /drafts/{id}/validations)。""" from app.api.deps import ensure_role ensure_role("builder") - return await _draft_view(session, await _draft_or_404(session, draft_id)) + return await _draft_view(session, await _draft_or_404(session, draft_id), ensure_records=True) @router.get("/drafts/{draft_id}/trial") @@ -1012,7 +1863,13 @@ async def get_draft_trial(draft_id: str, session: AsyncSession = Depends(get_ses """这份草稿的试跑:{run_id, status, metrics: [{id, name, rendered, value}], queries, error}。 状态只有 succeeded / failed / running 三种;指标值读试跑运行封存的口径卡(和口径试跑同一个读法),queries 是取数节点 - 交回的查询快照(前几行、遮罩列换成「已遮罩」,不含 SQL)。还没试跑(老草稿、起草失败)回 404。只读,不发起运行。""" + 交回的查询快照(前几行、遮罩列换成「已遮罩」,不含 SQL)。还没试跑(老草稿、起草失败)回 404。只读,不发起运行。 + + 另在 validation 里并进**这一次**试跑对应的验证记录(K05):状态、期望/实际、覆盖判断和审阅结论。每个分支的 + validation 形状一致({schema_version, execution, status, checks, record, covers_current, note}),没有记录时 + record 是 null、covers_current 是 null(三态:true / false / null 判不了),**不拿别的最新记录顶上**。响应原有的 + 键一个不改;试运行超时、晚些才完成且有稳定身份的那些在这里补记一条记录(见 _ensure_trial_records)。 + """ from app.api.deps import ensure_role ensure_role("builder") @@ -1022,26 +1879,74 @@ async def get_draft_trial(draft_id: str, session: AsyncSession = Depends(get_ses workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None if _doc_draft_workflow(workflow): trial = await _trial_view(session, trial, version=workflow.version, graph=workflow.graph) + await _ensure_trial_records(draft, trial) + brief = await _trial_record_brief(session, await _trial_record(session, draft.id, trial), + current=_current_materials(workflow)) if trial.get("status") == "stale": - return {**trial, "metrics": [], "queries": []} + return {**trial, "metrics": [], "queries": [], + "validation": {**await _trial_validation("", "stale", []), **brief}} run_id = trial.get("run_id") if not isinstance(run_id, str) or not run_id: if trial.get("status") in ("needs_input", "running"): - return {**trial, "metrics": [], "queries": []} + return {**trial, "metrics": [], "queries": [], + "validation": {**await _trial_validation("", str(trial.get("status") or ""), []), **brief}} raise HTTPException(404, "这份草稿还没有试运行") run = await session.get(Run, run_id) if run is None: return {"run_id": run_id, "status": _run_status(trial.get("status")), "metrics": [], "queries": [], + "validation": {**await _trial_validation("", _run_status(trial.get("status")), []), **brief}, "error": str(trial.get("error") or "")} status = _run_status(run.status) metrics = await _trial_metrics(run.id) if status == "succeeded" else [] queries = await _trial_queries(run.id) if status == "succeeded" else [] return {**trial, "run_id": run.id, "status": status, "metrics": metrics, "queries": queries, - "validation": await _trial_validation(run.id, status, metrics), "error": str(run.error or "")} + "validation": {**await _trial_validation(run.id, status, metrics), **brief}, + "error": str(run.error or "")} + + +class DraftExpectIn(BaseModel): + """这次试跑要对着比的**固定期望**(K05):独立于这次执行的一方给的标准答案。 + + metrics 是 metric_id → 期望的原值,要**逐条给全卡指标**(全指标比较,漏一条会拒);source 说明这份期望是谁给的 + (human_confirmed 人工确认 / fixture 固定夹具 / independent_computation 独立计算),**不能拿当前 SQL 的结果 + 抄一份当标准答案**。expected 原值比较、不做隐式舍入(R06)。 + """ + + model_config = ConfigDict(extra="forbid") + + metrics: dict[str, Any] + source: str = Field(default="human_confirmed", max_length=40) + sample_id: str | None = Field(default=None, max_length=120) + sample_version: str | None = Field(default=None, max_length=40) + note: str | None = Field(default=None, max_length=500) class DraftTrialIn(BaseModel): inputs: dict[str, Any] = Field(default_factory=dict) + #: 不带期望也能跑:那样这一条只记 observed,不能算验证通过(见 app/ledger/validation.py) + expect: DraftExpectIn | None = None + + +def _checked_expectation(expect: Mapping[str, Any], graph: dict[str, Any]) -> dict[str, Any]: + """校验这次试跑带的固定期望:指标必须是这张卡上的、要逐条给全,来源只能是三种之一。不合规回 422,不发起运行。""" + from app.ledger import validation + + card_id, cards = draft_card(graph) + card_id = str(card_id or (cards[0]["id"] if cards else "") or "") + metrics = validation.card_metrics(graph, card_id) + known = [str(metric["id"]) for metric in metrics] + given = expect.get("metrics") if isinstance(expect.get("metrics"), Mapping) else {} + unknown = sorted(str(mid) for mid in given if str(mid) not in known) + if unknown: + raise HTTPException(422, f"期望里有这张卡上没有的指标:{'、'.join(unknown)}") + missing = [mid for mid in known if mid not in {str(mid) for mid in given}] + if missing: + raise HTTPException(422, f"期望要逐条给全卡指标,还缺:{'、'.join(missing)}" + "(全指标比较:只给一部分不能算通过)") + source = expect.get("source") + if source is not None and str(source) not in validation.EXPECTATION_SOURCES: + raise HTTPException(422, f"期望来源只能是:{'、'.join(validation.EXPECTATION_SOURCES)}") + return expect @router.post("/drafts/{draft_id}/trial") @@ -1052,9 +1957,17 @@ async def run_draft_trial(draft_id: str, payload: DraftTrialIn, 自动试跑缺必填输入时停在 needs_input(不拿系统编的日期跑,那样跑出来的数没有意义),人在这里补上再跑。 参数按入口字段校验,和正式运行同一套(apps/forms);跑的仍是探针图:只取数与口径卡,不写报告、不进统计。成功时另给 queries(取数节点交回的查询快照,前几行、遮罩列换成「已遮罩」,不含 SQL);没有运行、失败或还在跑时为空数组。 + + 参数完整性(缺参数、未声明参数、值承载不了)按 ledger/params 同一套判:不合规时试跑**不发起**,状态记 needs_input + 并把原因写在 error 里(页面那一块就显示这句),一条 SQL 都不会发出去。 + + 带 expect(固定期望,K05)时:期望里的指标必须是这张卡上的、要逐条给全(不合规回 422,不发起运行);跑完按 + ledger/validation 的方法版本 1 比一遍(原值、全指标、全约定形状),结果连同这次的定义/绑定依据追加成一条验证 + 记录。不带 expect 也能跑,但那样这条只记 observed——没有独立期望就不能算验证通过。 """ from app.api.deps import current_principal, ensure_role from app.apps.forms import input_schema, validate_form + from app.ledger import params ensure_role("builder") draft = await _draft_or_404(session, draft_id) @@ -1075,19 +1988,114 @@ async def run_draft_trial(draft_id: str, payload: DraftTrialIn, unknown = sorted(set(payload.inputs) - {str(field.get("name")) for field in fields}) if unknown: raise HTTPException(422, f"不认识的入口字段:{'、'.join(unknown)}") + expect = payload.expect.model_dump(exclude_none=True) if payload.expect is not None else None + if expect is not None: + expect = _checked_expectation(expect, row.graph) values: dict[str, Any] = {str(field.get("name")): field.get("default") for field in fields if field.get("default") not in (None, "")} - values.update({str(key): value for key, value in payload.inputs.items()}) + # 和 trial_caliber 同一份收值(params.provided):显式空串算没给,字段没声明的缺省值就是缺参数 + values.update(params.provided(payload.inputs)) if errors := validate_form(input_schema(fields), values): raise HTTPException(422, ";".join(str(e.get("message")) for e in errors[:5])) trial = await _run_trial(draft_id=draft.id, workflow_id=str(workflow_id), graph=row.graph, values=values, started_by=current_principal().username, entry_fields=fields, version=version) - await _save_trial(draft.id, trial) + await _save_trial(draft.id, trial, expect=expect) + brief = await _trial_record_brief(session, await _trial_record(session, draft.id, trial), + current=_current_materials(workflow)) run_id = str(trial.get("run_id") or "") queries = await _trial_queries(run_id) if run_id and trial.get("status") == "succeeded" else [] metrics = await _trial_metrics(run_id) if run_id and trial.get("status") == "succeeded" else [] return {**trial, "metrics": metrics, "queries": queries, - "validation": await _trial_validation(run_id, str(trial.get("status") or ""), metrics)} + "validation": {**await _trial_validation(run_id, str(trial.get("status") or ""), metrics), **brief}} + + +#: 审阅决定的审计(subject 是那条验证记录):谁在什么依据上确认或驳回了哪一次验证 +REVIEW_ACTION = "ledger.validation.review" +REVIEW_SUBJECT_KIND = "caliber_validation_record" +#: 没有能记下来的主体时不做审阅:审批人必须来自服务端身份,不能由模型或请求体代写 +REVIEW_ACTOR_REQUIRED = "review_actor_required" + + +@router.get("/drafts/{draft_id}/validations") +async def list_draft_validations(draft_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """这份草稿的验证记录(K05,新的在前)+ 总情况 + 字段基线状态:K06 读的那份契约。 + + 每条记录给 covers_current(还覆盖不覆盖**当前**定义/绑定)、expected / actual / status,以及这条上最新的审阅 + (confirmed / rejected,附认证主体与确认范围)。`summary.verdict` 才是结论:没有记录是 none、记录都不覆盖当前 + 版本是 stale、只有独立期望对得上**并且**有认证审阅确认了这份记录**全部**指标才算 verified——**样例匹配本身不是 + 批准,只确认一部分也不是**(`summary.confirmed` / `summary.unconfirmed` 分别列出确认到的和还没确认的指标)。 + + 读之前会先把已经到终态、有稳定身份、还没记过的试运行补记一条(超时、晚些才完成的那些);没有身份的旧记录不补、 + 只读不改;记录只追加,不改写旧的。 + """ + from app.api.deps import ensure_role + from app.ledger import fieldbaseline + + ensure_role("builder") + draft = await _draft_or_404(session, draft_id) + workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None + payload = draft.payload if isinstance(draft.payload, dict) else {} + trial = payload.get("trial") if isinstance(payload.get("trial"), dict) else {} + if _doc_draft_workflow(workflow): + trial = await _trial_view(session, trial, version=workflow.version, graph=workflow.graph) + await _ensure_trial_records(draft, trial) + return {"draft_id": draft.id, "field_baseline": fieldbaseline.status_of(payload), + **await _draft_records(session, draft, workflow=workflow)} + + +class DraftReviewIn(BaseModel): + """对一条验证记录的审阅决定(K05):只收决定、范围和说明——**不收 actor**,审批人取服务端身份。""" + + model_config = ConfigDict(extra="forbid") + + decision: str = Field(min_length=1, max_length=20) + note: str | None = Field(default=None, max_length=500) + metrics: list[str] | None = Field(default=None, max_length=60) + + +@router.post("/drafts/{draft_id}/validations/{record_id}/review", status_code=201) +async def review_validation(draft_id: str, record_id: str, payload: DraftReviewIn, + session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """对一条验证记录做一次审阅(builder 及以上):confirmed(确认)或 rejected(驳回),**只追加**。 + + 审批人只来自服务端身份(关登录时是中间件按 X-Actor 解出的自报署名),请求体里没有 actor 这个键(多传回 422)—— + 模型和客户端都代写不了审批人,也不能靠「样例对得上」自动变成批准。决定绑定**所审记录**的定义/绑定/取数语义依据: + 定义或绑定之后改过,这条决定保留但不再覆盖新版本(covers_current=false,返回里的 record.review 会说清)。 + + 确认范围(metrics)可以不写(= 确认这份记录的全部指标)或写成它的一个子集;写空列表拒(422 review_scope)。 + 只确认一部分时这条决定本身有效,但草稿摘要不会给卡级 verified——`summary.unconfirmed` 列出还没被确认的指标。 + + 同一份记录可以再审(追加一条,显示用最新的一条);没有能记下来的主体时拒(409 review_actor_required)。 + 不建多级审批,也不因这条决定自动改草稿状态或发布任何东西。 + """ + from app.api.deps import current_principal, ensure_role + from app.auth.audit import record as audit + from app.ledger import review, validation + + ensure_role("builder") + draft = await _draft_or_404(session, draft_id) + record = await validation.get_record(session, draft.id, record_id) + if record is None: + raise HTTPException(404, "这份草稿上没有这条验证记录") + principal = current_principal() + if not principal.username: + raise CodedHTTPException(409, "审阅要有一个能记下来的主体:请带上身份(登录,或自报 X-Actor)再确认或驳回", + REVIEW_ACTOR_REQUIRED) + try: + made = await review.decide(session, draft_id=draft.id, record=record, decision=payload.decision, + actor=principal.username, verified=principal.verified, + scope=payload.metrics, note=payload.note) + except review.ReviewRefused as e: + raise CodedHTTPException(422, e.message, e.code, field="decision") from None + await audit(session, REVIEW_ACTION, REVIEW_SUBJECT_KIND, record.id, + data={"draft_id": draft.id, "decision": made.decision, "scope": made.scope, + "basis": made.basis}) + workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None + current = _current_materials(workflow) + await session.commit() + return {"ok": True, "draft_id": draft.id, + "record": validation.as_dict(record, current=current, + review=review.as_dict(made, current=current))} def _check_metrics(metrics: Any) -> list[dict[str, Any]]: @@ -1109,54 +2117,74 @@ def _check_metrics(metrics: Any) -> list[dict[str, Any]]: return [dict(metric) for metric in metrics] -async def _sync_draft_graph(session: AsyncSession, draft: CaliberDraft, payload_data: dict[str, Any]) -> None: - """在当前图上修改口径卡,再新增版本;取数节点、SQL、入口和用户添加的编排保持其身份。""" - from app.apps.versions import WorkflowChanged, save_graph - workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None - metrics = payload_data.get("metrics") - if not _doc_draft_workflow(workflow) or not isinstance(metrics, list): - return - graph = copy.deepcopy(workflow.graph) - card = next((n for n in graph.get("nodes") or [] if n.get("type") == "metrics" - and not (n.get("data", {}).get("config") or {}).get("caliber_from")), None) - if card is None: - raise HTTPException(409, "当前画布没有可编辑的口径卡,请先在画布上添加") - config = card.setdefault("data", {}).setdefault("config", {}) - old_ids = {m.get("id") for m in config.get("metrics") or [] if isinstance(m, dict)} - new_ids = [m.get("id") for m in metrics] - if any(not isinstance(mid, str) or not mid.strip() for mid in new_ids) or len(set(new_ids)) != len(new_ids): - raise ValueError("每条指标需要非空且唯一的 ID") - config["metrics"] = copy.deepcopy(metrics) - removed = old_ids - set(new_ids) - for node in graph.get("nodes") or []: - contract = node.get("data", {}).get("config", {}).get("contract") - if not isinstance(contract, dict): - continue - sources = contract.get("metrics_from") or [] - if card["id"] not in ([sources] if isinstance(sources, str) else sources): - continue - for key in ("required", "expected"): - if isinstance(contract.get(key), list): - before = contract[key] - contract[key] = list(new_ids) if key == "required" and set(before) == old_ids \ - else [mid for mid in before if mid not in removed] - try: - await save_graph(session, workflow, graph, note="编辑口径草稿") - except WorkflowChanged as e: - raise HTTPException(409, str(e)) from None - await session.flush() - live = await _draft_graph_payload(session, workflow, workflow.version) - if live is not None: - payload_data.update(live) +class DraftTargetIn(BaseModel): + """这次 PATCH 写哪张口径卡。图上有多张可写的卡时必须写明——不做「取第一张」。""" + + workflow_id: str | None = Field(default=None, max_length=32) + card_id: str | None = Field(default=None, max_length=64) + + +class DraftOperationIn(BaseModel): + """一条字段操作(K03):按稳定 metric_id + 字段路径改一处,不整份换指标。 + + value 只有 set 才有:省略 value 和写 null 是两件事(前者拒「set 要带 value」,后者拒「不能设成 null」; + 要「声明成空」写 '',数组写 []),remove 不接受 value。数组字段整份设置。能改哪些路径、每种的类型见 + app/ledger/changes.py——不认识的键直接拒(extra=forbid),不当没看见。 + """ + + model_config = ConfigDict(extra="forbid") + + op: str = Field(min_length=1, max_length=20) + metric_id: str = Field(min_length=1, max_length=64) + path: str = Field(min_length=1, max_length=120) + value: Any = None class DraftPatchIn(BaseModel): - """改标题、整体换掉指标、或把已经答清的问题消掉。""" + """改标题、整体换掉指标、把已经答清的问题消掉,或者按字段改一处(operations)。 + + 已接管的草稿(文档起草已经建出工作流的那些)还要带两样:expected_revision 是客户端读到的 Workflow.version + (两个页面先后保存时,后一个基于旧版本的要被拒,而不是盖掉前一个),request_id 是幂等键(重发不新增版本); + target 指明改哪张卡。没接管到工作流上的老草稿不看这三项,照旧只改 payload。 + + metrics(整份换)和 operations(按字段改)互斥:一次请求只落一版图,不把两条写路径串在一次里。resolved(消问题) + 也归整份那条路,不和 operations 混在一起。 + """ title: str | None = Field(default=None, max_length=200) metrics: list[dict[str, Any]] | None = None resolved: list[str] | None = None + #: 按字段改(K03):set / remove,每条指明 metric_id 和字段路径 + operations: list[DraftOperationIn] | None = Field(default=None, min_length=1, max_length=50) + #: 客户端拿着的基准版本(Workflow.version,读草稿时给的 revision) + expected_revision: int | None = Field(default=None, ge=1) + #: 幂等键:同一主体、同一工作流、同一张卡上重发同一个键不新增版本 + request_id: str | None = Field(default=None, min_length=1, max_length=64) + #: 这次写哪张卡(多张可写的卡时必须给) + target: DraftTargetIn | None = None + + +def _patch_fingerprint(payload: DraftPatchIn, card_id: str | None) -> str: + """这次请求的内容指纹:标题、指标、消掉的问题、字段操作、目标卡。不算 expected_revision——同一个 request_id + 带着过期的基准版本重放,认得出是同一件事,不报内容冲突。 + + resolved 归一成「去空白、去重、排序」的一份:消问题是按集合做的,勾选顺序变一下不该被当成另一次请求 + (客户端重发同一批问题时顺序可能不同)。operations 保持原顺序、按写下来的样子算(同一条指标上的几条是有先后的), + 「省略 value」和「写 null」也算不同的内容。 + + operations 这一项只在这次请求带了它的时候进指纹:不带的老请求算出来的还是原来那一份哈希,升级之前记下的 + request_id 照旧认得出是重放,不会突然变成「同键不同内容」。 + """ + from app.apps.versions import write_fingerprint + + resolved = None if payload.resolved is None else sorted( + {q.strip() for q in payload.resolved if isinstance(q, str) and q.strip()}) + content: dict[str, Any] = {"title": payload.title, "metrics": payload.metrics, "resolved": resolved, + "card": card_id or ""} + if payload.operations is not None: + content["operations"] = [op.model_dump(exclude_unset=True) for op in payload.operations] + return write_fingerprint(content) @router.patch("/drafts/{draft_id}") @@ -1164,11 +2192,30 @@ async def patch_draft(draft_id: str, payload: DraftPatchIn, session: AsyncSessio ) -> dict[str, Any]: """改一份草稿:metrics 整体替换(只做结构校验,不重跑引用核对);resolved 里的问题从跨指标和各指标的问题里删掉。 据此重算状态(还有问题 → questions_open,否则有图 → ready、没有图的老草稿 → path_pending)。已经 attach 或驳回的 - 草稿不改状态——那时它说的已经不是一份草稿了。""" - from app.api.deps import ensure_role + 草稿不改状态——那时它说的已经不是一份草稿了。 + + 已接管的草稿按 K02 的写入保护走:必须带 expected_revision(缺了回 409 revision_required)、目标卡要明确(多张 + 可写的卡没指明回 409 card_required,指到没有的卡回 409 card_not_found),基准版本过期回 409 stale_revision 并 + 带上 current_version(客户端保留自己的编辑,可显式重放);带了 request_id 的按主体 + 工作流 + 目标卡幂等,同键 + 同内容重放不新增版本、同键不同内容回 409 idempotency_conflict。幂等在版本检查之前判:上一次已经写进去的重放, + 即使基准版本已经过期也要成功。 + + operations 是 K03 的字段变更:按稳定 metric_id + 字段路径改一处(白名单和四种写法见 app/ledger/changes.py), + 改动打在原图的深拷贝上,没提到的字段、别的指标、扩展字段和其他节点原样保留;一批全成或全不成,失败不新增版本。 + 它和整份换指标(metrics)、消问题(resolved)互斥(422 change_conflict:一次请求只落一版图),回执里另带 change + 一段(变更分类、影响指标、定义指纹、失效说明和绑定状态)。带 request_id 的重放交回的是当前视图(带 replayed), + 不再重新算一份变更回执。 + """ + from app.api.deps import current_principal, ensure_role + from app.apps.versions import (REVISION_REQUIRED, STALE_REVISION, WRITE_CONFLICT, WRITE_REPLAY, claim_write, + remember_write, stale_revision_message) from sqlalchemy import update ensure_role("builder") + actor = current_principal().username + if payload.operations is not None and (payload.metrics is not None or payload.resolved is not None): + raise CodedHTTPException(422, "字段操作(operations)和整份换指标 / 消问题不能放在同一次请求里:" + "两条写路径各落一版图,请分开提交", CHANGE_CONFLICT, field="operations") # 和重试对同一草稿串行,SQLite 也通过写锁保护;后台还在生成时不接受会被它覆盖的编辑。 await session.execute(update(CaliberDraft).where(CaliberDraft.id == draft_id) .values(updated_at=CaliberDraft.updated_at).execution_options(synchronize_session=False)) @@ -1178,8 +2225,32 @@ async def patch_draft(draft_id: str, payload: DraftPatchIn, session: AsyncSessio body = draft.payload if isinstance(draft.payload, dict) else {} payload_data = copy.deepcopy(body) workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None - if _doc_draft_workflow(workflow): - live = await _draft_graph_payload(session, workflow, workflow.version) + taken_over = _doc_draft_workflow(workflow) + workflow_id = workflow.id if workflow is not None else None + card_id: str | None = None + fingerprint = "" + change: Any = None + if taken_over: + # 已接管:改哪张卡是明确的;写要带基准版本,重放要认得出 + card_id = _target_card(payload, workflow) if (payload.metrics is not None or payload.resolved is not None + or payload.operations is not None) else None + if payload.expected_revision is None: + raise CodedHTTPException( + 409, f"这份口径已经接管到工作流上(现在是 v{workflow.version}):修改要带上读到的版本(expected_revision)," + "请刷新页面后再改", REVISION_REQUIRED, extra={"current_version": workflow.version}) + fingerprint = _patch_fingerprint(payload, card_id) + claim = await claim_write(session, actor=actor, workflow_id=workflow_id, target=card_id, + request_id=payload.request_id, payload_hash=fingerprint) + if claim.state == WRITE_CONFLICT: + raise CodedHTTPException(409, "同一个 request_id 已经用不同的内容提交过:请换一个 request_id 再提交", + IDEMPOTENCY_CONFLICT, extra={"current_version": workflow.version}) + if claim.state == WRITE_REPLAY: + # 上一次已经写进去了:照上次的结果交回,不再新增版本(基准版本过期也不算冲突) + return {**await _draft_view(session, draft), "replayed": True} + if payload.expected_revision != workflow.version: + raise CodedHTTPException(409, stale_revision_message(workflow.version, payload.expected_revision), + STALE_REVISION, extra={"current_version": workflow.version}) + live = await _draft_graph_payload(session, workflow, workflow.version, card_id=card_id) if live is not None: payload_data.update(copy.deepcopy(live)) if payload.title is not None: @@ -1202,7 +2273,8 @@ async def patch_draft(draft_id: str, payload: DraftPatchIn, session: AsyncSessio if payload.metrics is not None or payload.resolved is not None: # 换指标、清问题都要落到图上:草稿页从图读,只改 payload 会被下一次读取覆盖回去 try: - await _sync_draft_graph(session, draft, payload_data) + await _sync_draft_graph(session, draft, payload_data, card_id=str(card_id), + expected_revision=payload.expected_revision) except ValueError as e: raise HTTPException(422, f"改完的指标建不成图:{e}") from e draft.payload = payload_data @@ -1211,8 +2283,44 @@ async def patch_draft(draft_id: str, payload: DraftPatchIn, session: AsyncSessio if isinstance(metrics, list) and metrics and draft.status in ("drafting", "questions_open", "path_pending", "ready", "failed"): draft.status = _status_for(payload_data) - await session.commit() - return await _draft_view(session, draft) + if payload.operations is not None: + # 按字段改(K03):和上面那条路互斥,一次请求只落一版图。状态不重算——改字段不动未决问题,也不动取数路径。 + change = await _sync_draft_changes(session, draft, payload_data, card_id=str(card_id), + expected_revision=payload.expected_revision, + operations=payload.operations) + draft.payload = payload_data + if taken_over: + await remember_write(session, actor=actor, workflow_id=workflow_id, target=card_id, + request_id=payload.request_id, payload_hash=fingerprint, + revision=workflow.version) + try: + await session.commit() + except IntegrityError: + # 两路真并发带同一个 request_id:后到的那一路在记请求时撞唯一键,回滚掉自己写的图,按赢的那一路交回。 + # 只有重查确认是同一件事(同键同内容)才当重放;记录还不存在(别处的完整性错误)照旧抛出去, + # 不能把没写成的请求报成成功。 + await session.rollback() + if not taken_over or not payload.request_id: + raise + reread = await _draft_or_404(session, draft_id) + claim = await claim_write(session, actor=actor, workflow_id=workflow_id, target=card_id, + request_id=payload.request_id, payload_hash=fingerprint) + if claim.state == WRITE_CONFLICT: + raise CodedHTTPException(409, "同一个 request_id 已经用不同的内容提交过:请换一个 request_id 再提交", + IDEMPOTENCY_CONFLICT) from None + if claim.state != WRITE_REPLAY: + raise + return {**await _draft_view(session, reread), "replayed": True} + return _with_change(await _draft_view(session, draft), change, revision=getattr(workflow, "version", None)) + + +def _with_change(view: dict[str, Any], change: Any, *, revision: int | None) -> dict[str, Any]: + """把 K03 的变更回执并进草稿视图(只有走 operations 的那条路才带)。""" + if change is None: + return view + from app.ledger import changes + + return {**view, "change": changes.summary(change, applied=bool(change.applied), revision=revision)} @router.post("/drafts/{draft_id}/retry") diff --git a/backend/app/api/runs.py b/backend/app/api/runs.py index fe570b3c..29bb9805 100644 --- a/backend/app/api/runs.py +++ b/backend/app/api/runs.py @@ -2,6 +2,9 @@ from __future__ import annotations import asyncio import contextlib +import json +import re +from collections.abc import Mapping from datetime import datetime from typing import Any @@ -12,7 +15,7 @@ from sqlalchemy.ext.asyncio import AsyncSession from app.api.coded import CodedHTTPException # 「人」的唯一入口搬到了 api/deps.py(开登录时返回认证过的用户名)。别处照旧从这里导入 actor_of -from app.api.deps import actor_of # noqa: F401 +from app.api.deps import actor_of, restricted # noqa: F401 from app.core.bus import bus from app.db.base import SessionLocal, get_session from app.db.models import Approval, Artifact, Run, RunEvent @@ -22,6 +25,8 @@ from app.engine.launch import ( # noqa: F401 TOOL_MISSING, LaunchRefused, launch_run, missing_tools, node_setting, tool_bindings, ) from app.engine.runner import run_manager +# 口径查询的真实工具名:投影里认「这个节点调的是口径查询」用它,别处不许另写一个字符串 +from app.ledger.querycore import CALIBER_QUERY router = APIRouter(prefix="/api/runs", tags=["runs"]) @@ -34,6 +39,197 @@ ORIGIN_REF_INVALID = "origin_ref_invalid" RUN_HAS_EFFECTS = "run_has_effects" +# -------------------------------------------------------------------------- +# 普通使用者的投影(K14):读得到的运行图上、事件流里,口径查询那一处不留内部身份 +# +# 规则本身在 auth/chat_policy(谁要按授权收窄)。这里只管**交出去的那一份**:开登录后 user 角色读自己这次运行(问数据的 +# origin_kind=chat + 在工具边界遮过,api/deps.run_events_readable)时,事件、运行图里的口径查询工具**参数**(哪张卡、哪一版)、 +# 工具结果(发布清单、selection、哈希、工件 id、参数材料)换成安全摘要——**存储一个字节都不动**,只在 API 这一层换一份。 +# 给人看的东西一件不少:算成没算成、状态、指标值(本来就遮过)、运行进度、别的节点的事件原样保留(不因为这里有一条口径 +# 查询就把普通聊天的事件清空)。builder 及以上读到的还是原件。 +# -------------------------------------------------------------------------- + +#: 留在事件里的字段(按整个数据字典白名单):都是「到哪一步了、算成没算成、花了多久」 +SAFE_EVENT_KEYS = ("tool", "label", "node_type", "duration_ms", "attempt", "outcome", "status", "timed_out", + "error", "ok", "truncated", "level", "code", "message", "to", "kind", "timing") +#: 留在工具结果摘要里的字段:结果本身(指标值、问题码)与它算成没算成 +SAFE_RESULT_KEYS = ("ok", "status", "metrics", "problems", "truncated") +#: 运行图里口径查询节点的参数换成这一句(口径身份不给:那是内部的事) +CALIBER_ARGS_NOTE = {"caliber": "按一份有授权的口径取数(卡与版本不在运行记录里给出)"} +#: 转抄卡(metrics.caliber_from)的身份映射换成这一句:它指的是哪一份工作流的哪一版、节点怎么对应,都不出去 +CALIBER_FROM_NOTE = {"caliber": "转抄自一份有授权的口径(工作流、版本与节点映射不在运行记录里给出)"} +#: 失败说法里的安全白话:口径那一档只给「没成功」+ 机器码(口径名、版本、card 都不带出来) +CALIBER_FAILED_TEXT = "按口径取数没有成功" +#: 提示词 / 说明里那份「取数写法」的键:口径身份那几个的值换成安全摘要(键、说明、inputs 的值都留着) +CALIBER_CALL_KEYS = ("workflow", "workflow_id", "workflow_version", "card", "card_id", "version", "node_id") +_CALL_VALUE = re.compile(r'("(?:' + "|".join(CALIBER_CALL_KEYS) + r')"\s*:\s*)"[^"]*"') +#: 失败事件(这几个类型才把 error / message 换成安全白话;log 的消息照旧给——它本来就没有口径身份) +FAILURE_EVENTS = ("node.failed", "tool.error", "run.failed") + + +def run_projection(graph: Any) -> _Projection | None: + """这次请求要不要给运行图、事件做投影:普通使用者要(交回投影),builder 及以上不要(交回 None,照原样给)。""" + return _Projection(graph) if restricted() else None + + +class _Projection: + """一次请求里这份投影:先把运行图上绑口径查询的节点认出来,之后按节点/工具名判每一条事件、每张图。""" + + def __init__(self, graph: Any) -> None: + self.nodes = _caliber_nodes(graph) + + def graph(self, graph: Any) -> Any: + """运行图:口径查询节点的参数、提示词与转抄卡的身份映射换成安全摘要,别的节点一个字不动。""" + if not isinstance(graph, dict): + return graph or {} + nodes = [] + for node in graph.get("nodes") or []: + config = _config_of(node) + if isinstance(node, dict) and isinstance(config, dict) and _touches_caliber(config): + node = {**node, "data": {**node["data"], "config": _safe_config(config)}} + nodes.append(node) + return {**graph, "nodes": nodes} + + def event(self, event: Any) -> Any: + """一条事件:口径查询那几处按白名单留字段(含工具结果的安全摘要、失败说法的安全白话),别的事件原样。 + + 判「是口径那一处」的几种写法:事件的节点是口径节点、工具是口径查询、失败事件里另带的口径节点 id(`run.failed` + 的节点写在 data 里,事件那一列是空的),或者这条失败说法本来就是口径那一档(认得出机器码/工具名)。""" + if not isinstance(event, dict): + return event + data = event.get("data") + if not isinstance(data, dict): + return event + node_id = str(event.get("node_id") or "") + failure = str(event.get("type") or "") in FAILURE_EVENTS + if node_id in self.nodes or str(data.get("tool") or "") == CALIBER_QUERY \ + or str(data.get("node_id") or "") in self.nodes \ + or (failure and safe_failure(data.get("error")) is not None): + safe = {k: v for k, v in data.items() if k in SAFE_EVENT_KEYS} + result = result_summary(data.get("artifact")) or safe_result(data.get("preview")) + if result is not None: + safe["result"] = result + if failure: + # 失败的那一条:口径名、版本、card 从说法里出去,机器码留着(人认得出是哪一档失败) + for key in ("error", "message"): + if key in safe: + safe[key] = safe_failure(safe[key]) + return {**event, "data": safe} + if "caliber" in data: + # 补固定的那条日志:源名、版本号留下,口径的固定目标(哪一份口径要的这版数据)不留给使用者 + return {**event, "data": {k: v for k, v in data.items() + if k not in ("caliber", "workflow_id", "version")}} + return event + + def failure(self, text: Any) -> Any: + """运行记录上那条失败说法:是口径那一档就换安全白话 + 机器码(`get_run` 的 error 用它)。""" + return safe_failure(text) or text + + +def _caliber_nodes(graph: Any) -> set[str]: + """这张图里与口径有关的节点 id:绑着口径查询的(调用工具节点写死的那个,Agent / 协作成员绑的也算),以及转抄卡 + (metrics.caliber_from)——两类都带着口径的身份,事件里按白名单给。""" + out: set[str] = set() + for node in (graph or {}).get("nodes") or []: + config = _config_of(node) + if isinstance(config, dict) and _touches_caliber(config): + out.add(str(node.get("id"))) + return out + + +def _touches_caliber(config: Mapping[str, Any]) -> bool: + """这个节点的配置里有没有口径的身份:绑了口径查询,或者是一张转抄卡。""" + bound = config.get("tools") if isinstance(config.get("tools"), list) else [] + if config.get("tool") == CALIBER_QUERY or CALIBER_QUERY in [t for t in bound if isinstance(t, str)]: + return True + return config.get("caliber_from") not in (None, "", {}) + + +def _safe_config(config: Mapping[str, Any]) -> dict[str, Any]: + """与口径有关的内部写法换成安全摘要:工具参数、提示词里的取数写法、转抄卡的身份映射。 + + 别的键(节点自己的说明、inputs 的值、工具清单)一个字不动——「使用者的图长什么样」照旧看得见,看不见的只是 + 「调的是哪一份工作流的哪一版」。""" + out = dict(config) + if out.get("tool") == CALIBER_QUERY and "args" in out: + out["args"] = dict(CALIBER_ARGS_NOTE) + bound = out.get("tools") if isinstance(out.get("tools"), list) else [] + if out.get("tool") == CALIBER_QUERY or CALIBER_QUERY in [t for t in bound if isinstance(t, str)]: + for key in ("prompt", "instructions"): + if key in out: + out[key] = safe_call_text(out[key]) + if out.get("caliber_from") not in (None, "", {}): + out["caliber_from"] = dict(CALIBER_FROM_NOTE) + return out + + +def safe_call_text(text: Any) -> Any: + """提示词 / 说明里那份「取数写法」:口径身份那几个键的**值**换成安全摘要,键名、说明、inputs 的值都留着。 + + 模型是照 look 交回的那一行(`{"workflow": "", "card": "", ...}`)写进 agent 提示词的:整行照抄最省事, + 所以这里按同一对键把它改掉——说明(「不要自己写取数 SQL」那几句)和要填的入口取值都还在,只是认不出是哪一份口径。""" + if not isinstance(text, str) or '"' not in text: + return text + return _CALL_VALUE.sub(lambda m: m.group(1) + '"(有授权的口径)"', text) + + +def safe_failure(text: Any) -> str | None: + """一条失败说法的安全白话:只留机器码,口径名、版本、card 一个字不带出来;不是口径那一档返回 None(照原样给)。 + + 认得出是口径那一档的两种写法:说法里有工具名(节点模板写的是「工具 caliber_query 执行失败:…」),或者有 querycore + 起 Run 之前拒绝的那几个机器码(口径固定执行在起 Run 之前拒时,码就写在消息里)。""" + from app.ledger.querycore import REFUSAL_CODES + + if not isinstance(text, str) or not text.strip(): + return None + code = next((code for code in REFUSAL_CODES if code in text), None) + if code is None and CALIBER_QUERY not in text: + return None + return f"{CALIBER_FAILED_TEXT}({code})" if code else CALIBER_FAILED_TEXT + + +def _config_of(node: Any) -> Any: + if not isinstance(node, dict) or not isinstance(node.get("data"), dict): + return None + return node["data"].get("config") + + +def result_summary(artifact: Any) -> dict[str, Any] | None: + """这次调用的**产出工件**里那份工具结果的安全摘要(本机文件,读不出来当没有)。 + + tool.end 的 preview 只留前 2000 个字符(一次口径查询交回的东西远超它),所以指标值、问题码从**工件本身**取: + 值本来就在工具边界遮过,这里只按白名单挑「算成没算成、值是多少」,口径身份、清单、selection、哈希、工件 id 都不出去。""" + if not artifact: + return None + from app.core.artifact_store import load + + try: + payload = load(str(artifact)) + except (ValueError, OSError): + return None + if isinstance(payload, dict) and isinstance(payload.get("result"), dict): + payload = payload["result"] # 工具快照包着 result;节点产出就是结果本身 + return _pick(payload) + + +def safe_result(preview: Any) -> dict[str, Any] | None: + """那条 preview(工具交回的整份结果,可能被截断)里的安全摘要:读不成 JSON 就当没有,不猜。""" + if not isinstance(preview, str) or not preview.lstrip().startswith("{"): + return None + try: + payload = json.loads(preview) + except ValueError: + return None + return _pick(payload) + + +def _pick(payload: Any) -> dict[str, Any] | None: + if not isinstance(payload, dict): + return None + out = {k: payload[k] for k in SAFE_RESULT_KEYS if payload.get(k) is not None} + return out if out.get("metrics") is not None or out.get("problems") is not None else None + + class OriginRef(BaseModel): @@ -125,6 +321,8 @@ async def start_run( options = None actor = actor_of(x_actor) memory_scope = payload.memory_scope + #: 这次要发起的图:使用者的那一档可能被 chat/launch 补上口径查询工具(见下面) + graph = payload.graph if restricted(): # user 角色(管理员开了问数据)只能发起问数据当场搭的探索运行:已发布工作流的正式运行只经应用入口发起,别的来源 # 都是搭建者的事。图里只许读数据、整理、撰写这一类节点和只读工具(app/auth/chat_policy.py)。 @@ -135,9 +333,10 @@ async def start_run( from app.auth.chat_policy import SCOPE_REFUSED from app.chat.launch import ChatRunRefused, user_chat_run - # 白名单、记忆范围、遮罩与只读这几条和服务端跑的一轮问数据(chat/job.py)共用 chat/launch.user_chat_run + # 白名单、记忆范围、遮罩与只读这几条和服务端跑的一轮问数据(chat/job.py)共用 chat/launch.user_chat_run; + # 它交回的图里可能已经补上了口径查询工具(有授权的口径那一份,见 chat/launch),发起用的是那一份 try: - memory_scope, options = user_chat_run(payload.graph, actor) + memory_scope, options, graph = await user_chat_run(session, payload.graph, actor) except ChatRunRefused as e: raise HTTPException(403, str(e)) from e if payload.memory_scope or payload.collection: @@ -146,7 +345,7 @@ async def start_run( return await launch_run( session, workflow_id=payload.workflow_id, - graph=payload.graph, + graph=graph, input_payload=payload.input, memory_scope=memory_scope, collection=payload.collection, @@ -290,6 +489,9 @@ async def get_run(run_id: str, session: AsyncSession = Depends(get_session)) -> if not run: raise HTTPException(404, "运行记录不存在") out = RunOut.model_validate(run) + if (projection := run_projection(run.graph)) is not None: + # 失败说法里那一句(口径名、版本、card)不给使用者看:换成安全白话 + 机器码,别的失败原样 + out.error = projection.failure(out.error) if out.status == "failed" and not out.error_node_id: # 加这一列之前失败的老运行:从事件里找最后一个失败的节点 out.error_node_id = (await session.execute( @@ -302,11 +504,17 @@ async def get_run(run_id: str, session: AsyncSession = Depends(get_session)) -> @router.get("/{run_id}/graph") async def get_run_graph(run_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: - """运行时的那张图(快照),不是工作流现在的样子。回放历史运行时画布照它画。""" + """运行时的那张图(快照),不是工作流现在的样子。回放历史运行时画布照它画。 + + 开登录后的使用者拿到的是一份**投影**(见 run_projection):图上口径查询节点的参数换成安全摘要,别的节点原样。""" run = await session.get(Run, run_id) if not run: raise HTTPException(404, "运行记录不存在") - return {"graph": run.graph or {}, "workflow_id": run.workflow_id, "version": run.version} + graph = run.graph or {} + projection = run_projection(graph) + if projection is not None: + graph = projection.graph(graph) + return {"graph": graph, "workflow_id": run.workflow_id, "version": run.version} @router.get("/{run_id}/events") @@ -315,13 +523,17 @@ async def get_events( after: int = 0, session: AsyncSession = Depends(get_session), ) -> list[dict[str, Any]]: - """拉历史事件。刷新页面后重建时间线用这个,再接 WebSocket 续上实时流。""" + """拉历史事件。刷新页面后重建时间线用这个,再接 WebSocket 续上实时流。 + + 开登录后的使用者拿到的是一份**投影**(见 run_projection):口径查询那几处按白名单给,别的节点的事件原样。""" + run = await session.get(Run, run_id) + projection = run_projection(run.graph if run is not None else None) rows = await session.execute( select(RunEvent) .where(RunEvent.run_id == run_id, RunEvent.seq > after) .order_by(RunEvent.seq) ) - return [ + events = [ { "id": e.id, "run_id": e.run_id, @@ -333,6 +545,7 @@ async def get_events( } for e in rows.scalars() ] + return [projection.event(event) for event in events] if projection is not None else events @router.get("/{run_id}/artifacts") @@ -617,6 +830,10 @@ async def stream_run(websocket: WebSocket, run_id: str) -> None: """ await websocket.accept() after = int(websocket.query_params.get("after", 0) or 0) + # 开登录后的使用者:实时流和历史回放是**同一条路**(下面两个都过同一个投影),见 run_projection + async with SessionLocal() as session: + run = await session.get(Run, run_id) + projection = run_projection(run.graph if run is not None else None) # 先占订阅位,再读历史。反过来的话,两步之间图正好跑出来的事件既不在 # 历史里、也不在实时流里——永远丢了。实测就是这样:一次跑图的开头 @@ -624,12 +841,12 @@ async def stream_run(websocket: WebSocket, run_id: str) -> None: # 在转圈、它的子步骤跑到了顶层。 subscription = bus.attach(run_id) try: - last_seq, run = await _replay(websocket, run_id, after) + last_seq, run = await _replay(websocket, run_id, after, projection) if run is not None and run.status in _SETTLED and run_manager.is_active(run_id): # 状态已经落了、执行任务还在收尾(终态事件、封存):等它收完,把这期间 # 落库的事件补上,按最终状态收尾。否则会在 run.finished 之前就宣布结束 await run_manager.wait_idle(run_id) - last_seq, run = await _replay(websocket, run_id, last_seq) + last_seq, run = await _replay(websocket, run_id, last_seq, projection) if run is None or run.status in _SETTLED: await _end(websocket, run.status if run else None) @@ -640,7 +857,7 @@ async def stream_run(websocket: WebSocket, run_id: str) -> None: from app.cluster.relay import relay with relay.follow_run(run_id, last_seq): - pump = asyncio.create_task(_pump(websocket, subscription.stream(after=last_seq), run_id)) + pump = asyncio.create_task(_pump(websocket, subscription.stream(after=last_seq), run_id, projection)) try: # 客户端断开时读操作会抛异常,用它来结束这条连接 while True: @@ -660,8 +877,11 @@ async def stream_run(websocket: WebSocket, run_id: str) -> None: subscription.close() -async def _replay(websocket: WebSocket, run_id: str, after: int) -> tuple[int, Run | None]: - """把 seq > after 的历史事件发出去,顺带取回运行当前的状态。""" +async def _replay(websocket: WebSocket, run_id: str, after: int, + projection: _Projection | None = None) -> tuple[int, Run | None]: + """把 seq > after 的历史事件发出去,顺带取回运行当前的状态。 + + projection 不为空(开登录后的使用者)时,事件先过一遍投影再发——历史回放和实时流走的是同一条路。""" last_seq = after async with SessionLocal() as session: rows = await session.execute( @@ -671,16 +891,15 @@ async def _replay(websocket: WebSocket, run_id: str, after: int) -> tuple[int, R ) for event in rows.scalars(): last_seq = max(last_seq, event.seq or 0) - await websocket.send_json( - { - "seq": event.seq, - "type": event.type, - "node_id": event.node_id, - "ts": event.ts, - "data": event.data, - "replay": True, - } - ) + wire = { + "seq": event.seq, + "type": event.type, + "node_id": event.node_id, + "ts": event.ts, + "data": event.data, + "replay": True, + } + await websocket.send_json(projection.event(wire) if projection is not None else wire) run = await session.get(Run, run_id) return last_seq, run @@ -691,10 +910,12 @@ async def _end(websocket: WebSocket, status: str | None) -> None: await websocket.close() -async def _pump(websocket: WebSocket, stream: Any, run_id: str) -> None: +async def _pump(websocket: WebSocket, stream: Any, run_id: str, + projection: _Projection | None = None) -> None: try: async for event in stream: - await websocket.send_json(event.to_wire()) + wire = event.to_wire() + await websocket.send_json(projection.event(wire) if projection is not None else wire) # 实时流走完 = 运行到了终态,或者关停时挂起了:补一条结束标记再关, # 客户端不用靠猜,也不会对着一条已经结束的运行无限重连 async with SessionLocal() as session: diff --git a/backend/app/api/workflows.py b/backend/app/api/workflows.py index 764d5836..20dc59c6 100644 --- a/backend/app/api/workflows.py +++ b/backend/app/api/workflows.py @@ -29,6 +29,8 @@ _GONE = "工作流不存在,可能已被删除" WORKFLOW_IN_USE = "workflow_in_use" #: 受管级发布、版本退役只给管理员(Q8) ADMIN_ONLY = "admin_only" +#: 把已接管资产(口径卡)的接管标记改掉被拒(K02/K07):那会同时丢掉改图的并发保护和发布依据的严格性 +PROTECTED_ASSET = "protected_asset" _LEVELS = ("published", "governed") _BAD_LEVEL = "发布级别只能是「已发布」或「受管」" #: 剩下的挡住发布的只有模型接入的问题、人又要交给助手时的说明:换成哪个接入要人拿主意,助手处理不了。发布弹窗里 @@ -65,6 +67,8 @@ class WorkflowPatch(BaseModel): graph: dict[str, Any] | None = None tags: list[str] | None = None note: str = "" + #: 客户端读到的 Workflow.version(K02 的乐观锁):画布每次都带,已接管的资产(文档起草的口径卡)改图时必须带 + expected_revision: int | None = Field(default=None, ge=1) class WorkflowOut(BaseModel): @@ -245,6 +249,20 @@ async def _checked_name(session: AsyncSession, workflow: Workflow, given: str) - return name +def _still_taken_over(workflow: Workflow, tags: list[str] | None) -> bool: + """换了这份标签之后还算不算「已接管」(K02/K07 的同一个标记):origin 里记着文档起草的一直算;只靠标签认的 + (从草稿接上一次运行建出来的那类)看新标签里还留着没有。tags 没给(这次不动它)按现在的算。 + + 标记本身只在 apps/versions.taken_over 一处认,这里只是把「换了标签之后」的那份状态喂给它,不另抄一份规则。 + """ + from types import SimpleNamespace + + from app.apps.versions import taken_over + + return taken_over(SimpleNamespace(origin=getattr(workflow, "origin", None), + tags=getattr(workflow, "tags", None) if tags is None else list(tags))) + + @router.patch("/{workflow_id}", response_model=WorkflowOut) async def update_workflow( workflow_id: str, payload: WorkflowPatch, session: AsyncSession = Depends(get_session) @@ -258,14 +276,33 @@ async def update_workflow( if payload.description is not None: workflow.description = payload.description if payload.tags is not None: + # 已接管的资产(文档起草的口径卡)不能靠改标签把自己降成普通工作流:K02 的并发保护、K07 的发布依据严格性都 + # 认这同一个标记,清掉它等于一次请求同时关掉两道保护(别的入口绕不过去的话就没有意义了)。加的标签照旧收, + # 只有「原来算接管、换完不算了」才拒;普通工作流一条不受影响 + from app.apps.versions import taken_over + + if taken_over(workflow) and not _still_taken_over(workflow, payload.tags): + raise CodedHTTPException( + 409, f"「{workflow.name}」已经接管到工作流上(现在是 v{workflow.version}):不能靠改标签把它降成普通" + "工作流。那会同时丢掉改图的并发保护和发布依据的严格性,已经发布的那些版本也不再按发布依据核对。" + "标签可以照常增改,但这一项标记要留着", PROTECTED_ASSET, + extra={"current_version": workflow.version, "tags": [str(t) for t in workflow.tags or []]}) workflow.tags = payload.tags if payload.graph is not None: - from app.apps.versions import WorkflowChanged, save_graph + from app.apps.versions import (REVISION_REQUIRED, STALE_REVISION, WorkflowChanged, save_graph, + taken_over) + if taken_over(workflow) and payload.expected_revision is None: + raise CodedHTTPException( + 409, f"这份口径已经接管到工作流上(现在是 v{workflow.version}):改图要带上你读到的版本" + "(expected_revision),请刷新页面后再改", REVISION_REQUIRED, + extra={"current_version": workflow.version}) try: - await save_graph(session, workflow, payload.graph, note=payload.note) + await save_graph(session, workflow, payload.graph, note=payload.note, + expected_revision=payload.expected_revision) except WorkflowChanged as e: - raise HTTPException(409, str(e)) from None + raise CodedHTTPException(409, str(e), STALE_REVISION, + extra={"current_version": getattr(e, "current", workflow.version)}) from None await session.commit() await session.refresh(workflow) return await _workflow_out(session, workflow) @@ -386,6 +423,9 @@ class VersionDetailOut(VersionOut): input_schema: dict[str, Any] = Field(default_factory=dict) #: 账本(L4):固定这一版的应用、生效记录数、正式运行数 usage: dict[str, Any] = Field(default_factory=dict) + #: 发布依据(K07):这一版最近一次发布留下的清单 {id, manifest, level, at, actor, proven, problems}。 + #: 加发布清单这一机制之前发布的版本为 null(老资产) + publication: dict[str, Any] | None = None @router.get("/{workflow_id}/versions/{version}", response_model=VersionDetailOut) @@ -416,8 +456,10 @@ async def get_version( if isinstance(f, dict) ) from app.apps.forms import input_schema + from app.apps.publications import basis_rows, latest as latest_publication from app.apps.versions import usage + event = await latest_publication(session, workflow_id, snapshot.version) return VersionDetailOut( id=snapshot.id, version=snapshot.version, note=snapshot.note, created_at=snapshot.created_at, workflow_id=workflow_id, graph=graph, @@ -430,6 +472,10 @@ async def get_version( input_schema=input_schema(fields), published_at=snapshot.published_at, published_by=snapshot.published_by, retired_at=snapshot.retired_at, retired_by=snapshot.retired_by, retire_note=snapshot.retire_note, usage=await usage(session, workflow_id, snapshot.version), + publication=({"id": event.id, "manifest": event.manifest, "level": event.level, + "at": event.created_at.isoformat() if event.created_at else None, "actor": event.actor, + "proven": bool(event.proven), "problems": basis_rows(event.cards)} + if event is not None else None), ) @@ -463,10 +509,27 @@ def _require_admin(what: str) -> None: raise CodedHTTPException(403, f"{what}需要管理员权限", ADMIN_ONLY) +class RestoreIn(BaseModel): + """回滚旧版本要带基准版本(K02):和画布保存、草稿改口径同一条并发规矩,已接管的资产必须给。""" + + expected_revision: int | None = Field(default=None, ge=1) + + @router.post("/{workflow_id}/versions/{version}/restore", response_model=WorkflowOut) async def restore_version( - workflow_id: str, version: int, session: AsyncSession = Depends(get_session) + workflow_id: str, version: int, payload: RestoreIn | None = None, + session: AsyncSession = Depends(get_session) ) -> WorkflowOut: + """回滚到某一版:在当前图上换成它的图、新增一版(旧版一条不动)。 + + 和保存同一条 CAS 规矩(app/apps/versions.append_version):带 expected_revision 就先核对,另一处已经先提交了 + 新版本也是 409 stale_revision(带 current_version),不会把别人刚改的图盖掉。已接管的资产(文档起草的口径卡) + 必须给基准版本,缺了回 409 revision_required——老页面不能靠这个入口绕过并发保护。恢复旧版也是改图,和 PATCH + 同一条规矩:旧图没过这次的闸,不能挂着受管 / 已发布。 + """ + from app.apps.versions import (REVISION_REQUIRED, STALE_REVISION, WorkflowChanged, append_version, + taken_over) + workflow = await session.get(Workflow, workflow_id) if not workflow: raise HTTPException(404, _GONE) @@ -481,20 +544,18 @@ async def restore_version( if not snapshot: raise HTTPException(404, f"不存在 v{version} 版本") - workflow.graph = snapshot.graph - workflow.version += 1 - session.add( - WorkflowVersion( - workflow_id=workflow.id, - version=workflow.version, - graph=snapshot.graph, - graph_hash=graph_hash(snapshot.graph), - note=f"回滚到 v{version}", - ) - ) - # 恢复旧版也是改图,和 PATCH 同一条规矩:旧图没过这次的闸,不能挂着受管 / 已发布 - if workflow.status in ("published", "governed"): - workflow.status = "draft" + expected = payload.expected_revision if payload is not None else None + if taken_over(workflow) and expected is None: + raise CodedHTTPException( + 409, f"这份口径已经接管到工作流上(现在是 v{workflow.version}):回滚要带上你读到的版本" + "(expected_revision),请刷新页面后再做", REVISION_REQUIRED, + extra={"current_version": workflow.version}) + try: + await append_version(session, workflow, snapshot.graph, note=f"回滚到 v{version}", + expected_revision=expected, digest=graph_hash(snapshot.graph)) + except WorkflowChanged as e: + raise CodedHTTPException(409, str(e), STALE_REVISION, + extra={"current_version": getattr(e, "current", workflow.version)}) from None await session.commit() await session.refresh(workflow) return await _workflow_out(session, workflow) @@ -570,22 +631,36 @@ from app.apps.validation import gate_issues async def commit_publish(session: AsyncSession, workflow: Workflow, snapshot: WorkflowVersion, level: str, actor: str | None) -> dict[str, Any]: - """把这一版立为正式版本并提交(调用方先过了 gate_issues、权限)。发布接口和发布单共用。""" + """把这一版立为正式版本并提交(调用方先过了 gate_issues、权限)。发布接口和发布单共用。 + + **发布只有一个入口**(K07):这里追加一行不可变的发布事件、落一份内容寻址的清单工件,记下这一版按什么依据发布。 + 重发旧版产生新事件,旧事件和旧清单一个字不改;版本行上这几列发布元数据是最新投影。既有门禁与 HTTP 语义不变。 + """ # 发布时用到的能力的治理版本(F5)。在改这一版之前取:能力登记缺了的要另开会话同步、提交,这个会话手里不能先有写 + from app.apps import publications from app.capabilities.registry import capability_versions_for from app.db.base import utcnow from app.engine.launch import graph_tool_names spec = GraphSpec.model_validate(snapshot.graph) capabilities = await capability_versions_for(session, graph_tool_names(snapshot.graph)) + # 发布时的目录版本、表的结构版本(next-round 03 B1):也是这一版图上的读取,先算好 + catalog = await catalog_versions_for(session, spec) + schema = await schema_versions_for(session, spec) + # 发布依据(K07):清单工件由另一个会话按内容寻址写下,所以必须在改这一版之前做(上面那句注释同一个道理, + # 这个会话手里先有未提交的写的话,两个会话会抢同一把写锁)。清单内容只由这一版不可变的图 + 引用的记录决定。 + publication = await publications.publish( + session, workflow=workflow, snapshot=snapshot, level=level, actor=actor, + observed=await publications.observe(session, workflow=workflow, snapshot=snapshot, catalog=catalog, + schema=schema, capabilities=capabilities)) if not snapshot.graph_hash: snapshot.graph_hash = graph_hash(snapshot.graph) # 级别记在这一版上:之后改画布(status 退回 draft),从这一版发起的正式运行照样按发布时的级别出具 snapshot.level = level # 发布时的目录版本也记在这一版上:重新发布同一版等于按现在的目录重新认可它,跟着更新 - snapshot.catalog_versions = await catalog_versions_for(session, spec) - # 表的结构版本同理(next-round 03 B1):正式运行发起时和现在的比,变了写 schema.drift,只提醒、不拦 - snapshot.schema_versions = await schema_versions_for(session, spec) + snapshot.catalog_versions = catalog + # 表的结构版本同理:正式运行发起时和现在的比,变了写 schema.drift,只提醒、不拦 + snapshot.schema_versions = schema # 发布人、发布时间、用到的能力版本也记在这一版上(F5):工作流上的 published_by 只记最近一次。退役过的版本重新 # 发布等于重新认可它,退役信息清掉 snapshot.published_at = utcnow() @@ -595,6 +670,7 @@ async def commit_publish(session: AsyncSession, workflow: Workflow, snapshot: Wo workflow.status = level workflow.published_version = snapshot.version workflow.published_by = actor + # 发布事件和版本行上的最新投影同一个事务提交:发布这一步没提交,事件也不会落(「发布失败无事件」) await session.commit() # 口径账本(next-round 02 做法 8):从问数据固化出的口径发布了,来源运行在后台按它补比一次(不挡发布) from app.ledger import recall as ledger_recall @@ -610,6 +686,11 @@ async def commit_publish(session: AsyncSession, workflow: Workflow, snapshot: Wo "graph_hash": snapshot.graph_hash, "published_by": workflow.published_by, "catalog_versions": recorded_versions(snapshot.catalog_versions), + # K07:这一次发布实际留下的发布依据。旧键一个不动,下面这几项是新增的 + "publication": {"id": publication["id"], "manifest": publication["manifest"], "format": publication["format"], + "proven": publication["proven"], "required": publication["required"], + "problems": publication["problems"], "cards": publication["cards"]}, + "manifest": publication["manifest"], } diff --git a/backend/app/apps/access.py b/backend/app/apps/access.py index 27a9b4f5..97b34b63 100644 --- a/backend/app/apps/access.py +++ b/backend/app/apps/access.py @@ -8,12 +8,17 @@ - 个人应用(scope=personal,docs/design/normal-user-apps.md N7):只有拥有者能用,按 manage 算(改页面、刷新、提交审核); 别人一律没有权限、看不到,管理员也一样——管理员只在应用列表里看得到它存在、能归档(can_archive),不看内容(P4)。 个人应用没有授权(不能分享),授权表里不会有它。 + +**口径资产授权**(usable_calibers / caliber_role / caliber_granting_app,文件末尾):普通使用者按口径问数、按口径出具时, +「我能不能用这一版口径」看的是同一张 AppGrant,对象换成应用当前发布版固定下来的那一版口径(AppVersion.pins,工作流和版本 +都要精确对上)。给本人、给他所在的组、给所有人的授权都算,至少 use;同一版取最高档。**builder / admin / 关登录不在这里 +放行**——调用方先显式放行,这几个函数只判「授权有没有把这一版口径给到这个主体」。 """ from __future__ import annotations from typing import Any -from sqlalchemy import select +from sqlalchemy import and_, select from sqlalchemy.ext.asyncio import AsyncSession from app.api.deps import Principal @@ -81,3 +86,110 @@ async def app_role(session: AsyncSession, principal: Principal, app: Any) -> str if principal.mode == "off" or principal.role == "admin": return "manage" return role_of(principal, app, await grants_of(session, app.id)) + + +# -------------------------------------------------------------------------- +# 口径资产授权:应用授权把哪几版口径给了这个主体(普通使用者「我能用哪些口径」) +# -------------------------------------------------------------------------- + +async def _subject(session: AsyncSession, actor: Any) -> Principal | None: + """按谁判口径资产授权:actor 可以是这次请求的 Principal,也可以是用户名。没有主体时 None。 + + - 用户名(或以 username 为身份的对象):从名录取组,授权本来就是按名字授的,署名、服务账号、名录里还没有的人都照名字算; + - 停用的人算没有主体(auth/directory:停用的人在名录里,认得出「这个人停用了」,不是「没有这个人」); + - actor 为空、用户名为空(关登录时署名可以是空的)都算没有主体。 + 角色(builder / admin)和关登录都不在这里放行:由调用方决定。 + """ + from app.auth.sessions import groups_of + from app.db.models import User + + if actor is None: + return None + if isinstance(actor, str): + name, groups = actor.strip(), () + else: + name = str(getattr(actor, "username", "") or "").strip() + groups = tuple(getattr(actor, "groups", ()) or ()) + if not name: + return None + user = (await session.execute(select(User).where(User.username == name))).scalars().first() + if user is not None: + if user.disabled: + return None + if not groups: + groups = await groups_of(session, user.id) + return Principal(username=name, role="user", groups=groups) + + +def _pinned_key(pin: Any) -> tuple[str, int] | None: + """AppVersion.pins 里的一项指的是哪一版口径:工作流和版本都要在,版本认不成整数的不算。""" + if not isinstance(pin, dict) or not pin.get("workflow_id") or pin.get("version") is None: + return None + try: + return str(pin["workflow_id"]), int(pin["version"]) + except (TypeError, ValueError): + return None + + +async def _caliber_grants(session: AsyncSession, actor: Any) -> dict[tuple[str, int], tuple[str, str]]: + """这个主体能按哪些(工作流, 版本)用:{(workflow_id, version): (最高一档授权, 靠哪一份应用)}。 + + 只看**未归档应用的当前发布版**固定着的版本(AppVersion.pins,工作流和版本都精确对上):应用升过级、不再固定它的旧版本 + 不算「正在用」,草稿里的固定也不算。授权按 AppGrant 取给本人、他所在的组、所有人的最高一档,低于 use 的不算。 + """ + from app.db.models_apps import App, AppVersion + + subject = await _subject(session, actor) + if subject is None: + return {} + rows = (await session.execute( + select(App.id, AppVersion.pins) + .join(AppVersion, and_(AppVersion.app_id == App.id, AppVersion.version == App.published_version)) + .where(App.status != "archived").order_by(App.id))).all() + found: dict[tuple[str, int], tuple[str, str]] = {} + for app_id, pins in rows: + role = granted_role(subject, await grants_of(session, app_id)) + if not at_least(role, "use"): + continue + for pin in pins or []: + key = _pinned_key(pin) + if key is not None and RANK.get(role, 0) > RANK.get((found.get(key) or ("",))[0], 0): + found[key] = (role, app_id) + return found + + +async def _lookup(session: AsyncSession, actor: Any, workflow_id: str, version: int) -> tuple[str, str] | None: + """问的这一版在这个主体的授权表里吗:在就给(最高一档授权, 靠哪一份应用),问的版本认不成整数就是不在。""" + try: + key = (str(workflow_id), int(version)) + except (TypeError, ValueError): + return None + return (await _caliber_grants(session, actor)).get(key) + + +async def usable_calibers(session: AsyncSession, actor: Any) -> dict[tuple[str, int], str]: + """这个主体能按哪些口径版本使用:{(workflow_id, version): 最高一档授权}(use / observe / manage)。 + + 「能用」= 未归档应用的当前发布版精确固定着这一版(AppVersion.pins),且 AppGrant 里给了他本人、他所在的组或所有人 + 至少 use 的授权。没有主体、停用、没有授权的口径不在表里(不是记 None)。builder / admin / 关登录由调用方先放行。 + """ + return {key: role for key, (role, _) in (await _caliber_grants(session, actor)).items()} + + +async def caliber_role(session: AsyncSession, actor: Any, workflow_id: str, version: int) -> str | None: + """这个主体按这一版口径拿到的最高一档资产授权;没有主体、停用、没有授权都是 None。 + + 调用方判「谁是使用者」:builder / admin / 关登录、以及个人应用、共享链接这些身份,各自在自己的入口先放行或收窄, + 这里只回答「授权有没有把这一版口径给到这个主体」。 + """ + found = await _lookup(session, actor, workflow_id, version) + return found[0] if found else None + + +async def caliber_granting_app(session: AsyncSession, actor: Any, workflow_id: str, version: int) -> str | None: + """这一版的资产授权是靠哪一份应用给的(和 caliber_role 同一份判定,最高档的那份):没有为 None。 + + 正式出具(ledger/issue)把它记进 run.origin.granted_by_app:使用者能按这一版出具,靠的是哪个应用的授权。 + """ + found = await _lookup(session, actor, workflow_id, version) + return found[1] if found else None diff --git a/backend/app/apps/publications.py b/backend/app/apps/publications.py new file mode 100644 index 00000000..57e94a6a --- /dev/null +++ b/backend/app/apps/publications.py @@ -0,0 +1,1203 @@ +"""最小发布依据(K07):每次发布留一份不可变清单,正式用途按它判。 + +**清单是什么。** 发布(api/workflows.py 的 commit_publish——发布只有一个入口,发布单也走它)时按这一版**不可变**的图 +算出一份确定的内容,存进内容寻址工件库(kind=caliber_publication,格式 agentlab.publication/1),再在 +workflow_publications 上**追加**一行发布事件。清单固定:图指纹、每张源头口径卡的定义指纹/绑定指纹/取数语义指纹/指标 +清单、参数契约、当前的取数依赖(数据源、表、固定版本的上游)、编译器约定(图/绑定/参数契约/验证方法,以及依赖闭包的 +解析器版本;K09 的固定执行按 `compiler_problems` 逐项核对),以及发布这一刻引用的 ValidationRecord 与 ReviewDecision。 + +**清单尽量确定。** 内容只由原始输入决定:这一版不可变的图 + 它引用的那两行记录(定义/绑定/语义指纹、指标、状态、范围 +这些**值**都写进内容,同时记下它们的 id)。发布人、发布时间、目录/结构/能力版本、绑定工具现在在不在,这些是**观察到的 +环境**,不进内容,单独记在事件行的 `observed` 上。于是: + +- 同一版重发一次、引用的记录也没变时,清单内容一字不差(工件哈希相同,只多一行事件); +- 原始输入还在时任何一刻都能按它重建同一份内容(rebuild);重建不上(版本行没了、引用的记录被删了、工件读不出来) + 一律**明确失败**并给机器码,不猜、不拿别的版本顶。 + +**重发旧版。** 每次发布都追加新事件,旧事件和旧清单一个字不改。发布指针 Workflow.published_version 是**推荐指针** +(默认调用读哪一版),最新一次发布事件和它一致;最高已发布版另算(apps/versions.latest_published,只用于升级发现, +见 upgrade_of)。**显式版本请求始终固定到指定的那一版**。老资产不 backfill:加这张表之前发布过的版本没有事件, +读的时候按「老资产」处理(身份 formal_legacy),不补造历史。 + +**用途判定(purpose)。** purpose 由**服务端入口常量**决定,不由客户端传:trial(试算/试运行)、explore(探索:问数据、 +画布、目录)、compose(组合式问数选用口径)、formal(正式运行)、issue(按口径出具)。只有 formal / issue 会因为发布 +依据不足被拒;试算、探索、组合一条都不受这套门禁影响(A03、A07:口径不是所有问数的前置手续)。 + +**requires_proof。** 只对「这一版有发布事件、而且**发布时要求过证明**(事件行上的 required)或**现在还接管着** +(apps/versions.taken_over)」的资产启用——两者取或:发布那一刻的严格性记在事件行上,之后把接管标记去掉(清 tags 之类) +不会让已经按严格发的那些版本降级;发布之后才接管上的照旧要证明。正式运行/出具时,这一版的发布依据必须**过这几道**: +先核工件本身(`read()` 复验内容哈希、就是这一版这一份,`compiler_problems()` 核编译器约定——和 K09 的固定执行同一份 +核对,工件被删/被改/按别的约定物化的都不能继续正式执行);再核清单是不是**就是这一版这一张图**的(图指纹对得上、 +图上的源头口径卡一张不缺);再逐张卡比清单里引用的那一对记录/审阅(**最新的那条**覆盖这一版的验证记录是 matched, +并且有认证主体确认**覆盖这份记录全部指标**的审阅决定——只确认一部分不算,同 K05:空范围、部分范围都不算整张卡被确认, +不在这时候另挑更新的记录补、清单里没有的卡也不现场挑一条顶上);最后按同一用途**递归判转抄卡(caliber_from)固定引用的 +上游那一张卡**——上游要证明就得同样满足,失败按上游那条机器码加下游引用拒,只判被引用的那张卡、循环引用截断、上游是老 +资产的不升级。不满足各有机器码:清单工件不在/被改过/不是这一份、编译器约定不认、清单不是这一张图的/缺卡、缺记录、旧 +记录不覆盖这一版、不是 matched、审阅被驳回、只确认了一部分、引用的记录/审阅不在。老资产(这一版没有清单)保持原行为, +只是记身份 formal_legacy;不需要证明的记 formal_unproven——**两者都不是 verified**。 +""" +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field, replace +from typing import Any + +from sqlalchemy import select + +from app.apps import versions as app_versions + +#: 清单工件的种类与内容格式 +KIND = "caliber_publication" +FORMAT = "agentlab.publication/1" + +# -------------------------------------------------------------------------- +# 用途(服务端入口常量)与身份 +# -------------------------------------------------------------------------- + +#: 试算/试运行(口径试跑、蓝图试运行):探索运行,不继承正式身份 +PURPOSE_TRIAL = "trial" +#: 探索:问数据当场搭的、画布试跑、目录与 look 的默认查看、账本比对挑候选 +PURPOSE_EXPLORE = "explore" +#: 组合式问数选用一份口径(ledger/compose) +PURPOSE_COMPOSE = "compose" +#: 正式运行(engine/launch.launch_run 的 run_class=formal) +PURPOSE_FORMAL = "formal" +#: 按口径出具(ledger/issue) +PURPOSE_ISSUE = "issue" + +PURPOSES = (PURPOSE_TRIAL, PURPOSE_EXPLORE, PURPOSE_COMPOSE, PURPOSE_FORMAL, PURPOSE_ISSUE) +#: 会按发布依据拦的用途:只有正式运行和出具 +PROOF_PURPOSES = (PURPOSE_FORMAL, PURPOSE_ISSUE) + +#: 正式运行的身份。**没有 verified 这一档**:发布依据齐全才叫 proven,需要证明而没证明的叫 unproven, +#: 老资产(这一版没有清单)叫 legacy——后两者都保持原来的行为,但都不能被说成「验证过了」 +PROVEN = "formal_proven" +UNPROVEN = "formal_unproven" +LEGACY = "formal_legacy" +IDENTITIES = (PROVEN, UNPROVEN, LEGACY) + +# -------------------------------------------------------------------------- +# 机器码(拒绝时给程序认) +# -------------------------------------------------------------------------- + +#: 这一版没有发布依据(没有发布事件):老资产或还没发布过 +BASIS_MISSING = "publication_basis_missing" +#: 清单与这一版对不上(定义/绑定/取数语义指纹不同):不拿它证明这一版 +BASIS_MISMATCH = "publication_basis_mismatch" +#: 这张卡没有留下任何验证记录 +RECORD_MISSING = "publication_record_missing" +#: 有记录,但没有一条覆盖这一版的定义/绑定/取数语义(旧记录、改过定义) +RECORD_STALE = "publication_record_stale" +#: 有覆盖这一版的记录,但不是 matched(observed / unverified / mismatched / failed) +RECORD_NOT_MATCHED = "publication_record_not_matched" +#: 没有审阅决定 +REVIEW_MISSING = "publication_review_missing" +#: 审阅决定绑的依据不是这一版(定义/绑定改过之后) +REVIEW_STALE = "publication_review_stale" +#: 审阅驳回了 +REVIEW_REJECTED = "publication_review_rejected" +#: 只确认了一部分指标:部分审阅不算覆盖全部指标 +REVIEW_PARTIAL = "publication_review_partial" +#: 审阅不是认证主体做的(这套部署开着登录,而那条决定记的是自报署名) +REVIEW_UNVERIFIED = "publication_review_unverified" +#: 清单引用的验证记录/审阅决定已经不在库里(原始输入缺失,重建不上) +INPUTS_MISSING = "publication_inputs_missing" +#: 清单工件不在 +MANIFEST_MISSING = "publication_manifest_missing" +#: 清单工件与哈希不符(被改过) +MANIFEST_TAMPERED = "publication_manifest_tampered" +#: 工件不是这一版这一份清单 +MANIFEST_FOREIGN = "publication_manifest_foreign" +#: 清单里没有编译器约定(认不出它是按哪一套物化的) +COMPILER_MISSING = "publication_compiler_missing" +#: 清单里的编译器约定和现在这一套对不上(A09:该拒的是执行,不是按新规则重解释旧发布) +COMPILER_MISMATCH = "publication_compiler_mismatch" + +#: 拒绝时给的那句话(机器码 → 白话),reason 更具体时用 reason +CODE_TEXT = { + BASIS_MISSING: "这一版没有发布依据(发布清单)", + BASIS_MISMATCH: "这一版的发布清单和它现在的定义/绑定对不上", + RECORD_MISSING: "这一版没有留下任何验证记录", + RECORD_STALE: "这一版现有的验证记录都不是对着它现在的定义和绑定做的", + RECORD_NOT_MATCHED: "这一版最新的验证记录不是「有独立期望、逐条对得上」的(matched)", + REVIEW_MISSING: "这一版的验证记录还没有经过认证审阅", + REVIEW_STALE: "这一版的审阅决定绑的是改之前的定义/绑定", + REVIEW_REJECTED: "这一版的验证记录被审阅驳回了", + REVIEW_PARTIAL: "这一版的审阅只确认了一部分指标", + REVIEW_UNVERIFIED: "这一版的审阅不是认证主体做的", + INPUTS_MISSING: "这一版发布依据引用的验证记录或审阅决定已经不在库里,重建不上", +} + + +# -------------------------------------------------------------------------- +# 编译器与验证方法的版本(A09:执行时禁止按新版编译器悄悄重解释旧发布物) +# -------------------------------------------------------------------------- + + +#: 清单自己的约定版本(格式串里那一版的编号) +MANIFEST_VERSION = 1 +#: 执行定义的规范形式版本:和 core/artifact_store.execution_content 的 schema_version 对应(图指纹按它算) +GRAPH_SCHEMA = 1 +#: 参数契约里每条字段的键(app/ledger/params.contract 的形状) +CONTRACT_FIELDS = ("name", "type", "required", "default") +#: 编译器约定里必须逐项核对的键(K09 的固定执行按它判「这一版认不认这份清单」):少一项、多一项都算不兼容 +COMPILER_KEYS = ("manifest", "graph_schema", "binding", "parameters", "validation_method", "resolver") + + +def compiler_versions() -> dict[str, Any]: + """这份清单是按哪一套确定性约定物化出来的:图/绑定的编译器版本、参数契约的承载方式、验证方法的版本、 + 依赖闭包的解析器版本。 + + A09:执行时不许按新版编译器悄悄重解释旧发布物。清单里把它写死,读的人(和以后换实现的人)能看出这一版是按 + 哪一版约定物化的;版本不兼容时该拒绝的是执行,不是拿新规则去解释旧依据(`compiler_problems` 是那道核对)。 + """ + from app.ledger import bindings, closure, params, validation + + return { + "manifest": MANIFEST_VERSION, + "graph_schema": GRAPH_SCHEMA, + "binding": {"binder": bindings.BINDER, "version": bindings.BINDER_VERSION}, + "parameters": {"adapter": params.ADAPTER, "contract_fields": list(CONTRACT_FIELDS)}, + "validation_method": validation.METHOD_VERSION, + "resolver": closure.RESOLVER_VERSION, + } + + +def compiler_problems(content: Mapping[str, Any]) -> list[dict[str, Any]]: + """这份清单物化时用的那一套约定,现在这一套认不认(逐项比对 `compiler_versions()`)。 + + 对不上、缺项、多出认不出的项都给一条 {code, key, message}:调用方据此**拒绝对这一版的固定执行**,绝不按新规则 + 现场重解释旧发布。老清单(加 resolver 这一项之前发的)缺 `resolver` 也在这里拒——认不出它按哪一版闭包解析的, + 就不该假装认得。 + """ + from app.core.artifact_store import canonical_json + + recorded = content.get("compiler") if isinstance(content, Mapping) else None + if not isinstance(recorded, Mapping): + return [{"code": COMPILER_MISSING, "key": "compiler", "message": "发布清单里没有编译器约定:" + "认不出它是按哪一套确定性约定物化的,不能按现在这一套执行"}] + wanted = compiler_versions() + problems: list[dict[str, Any]] = [] + for key in COMPILER_KEYS: + if canonical_json(recorded.get(key)) != canonical_json(wanted.get(key)): + problems.append({"code": COMPILER_MISMATCH, "key": key, + "message": f"发布清单里的「{key}」约定({canonical_json(recorded.get(key))})" + f"和现在这一套({canonical_json(wanted.get(key))})不一致"}) + for key in sorted(set(recorded) - set(COMPILER_KEYS)): + problems.append({"code": COMPILER_MISMATCH, "key": str(key), + "message": f"发布清单里有一项现在认不出的编译约定「{key}」"}) + return problems + + +# -------------------------------------------------------------------------- +# 内容:图上的确定部分 +# -------------------------------------------------------------------------- + + +def source_cards(graph: Any) -> list[dict[str, Any]]: + """图里的源头口径卡:[{id, title, caliber, caliber_version}],按节点在图里的先后。 + + 和 K02/K03 认权威写入源是同一套(api/ledger.editable_cards):只有源头口径卡(metrics 节点、没有 caliber_from), + 转抄别处的口径卡不算一份自己的定义。 + """ + from app.apps.tree import node_map + + out: list[dict[str, Any]] = [] + for node_id, node in node_map(graph).items(): + if node.get("type") != "metrics" or (node.get("config") or {}).get("caliber_from") not in (None, "", {}): + continue + config = node.get("config") or {} + out.append({"id": node_id, "title": str(node.get("title") or node_id), + "caliber": str(config.get("caliber") or ""), + "caliber_version": str(config.get("caliber_version") or "")}) + return out + + +def fetch_dependencies(graph: Any) -> tuple[list[str], list[str]]: + """图里取数用的数据源名和表名(去库名前缀),按名字排序。 + + 只认调用数据库查询工具、工具名不带模板、并且写了 SQL 的节点——模板拼出来的工具名认不出「哪一版库」。 + **不读 SQL 正文**:SQL 里可能写着遮罩值,清单只记依赖的名字。 + """ + from app.apps.tree import node_map + from app.engine.evidence import sql_tables + from app.tools.datasource import QUERY_PREFIX + + sources: set[str] = set() + tables: set[str] = set() + for node in node_map(graph).values(): + if node.get("type") != "tool": + continue + config = node.get("config") or {} + tool = str(config.get("tool") or "") + args = config.get("args") + sql = args.get("sql") if isinstance(args, dict) else None + if not tool.startswith(QUERY_PREFIX) or "{{" in tool or not isinstance(sql, str) or not sql.strip(): + continue + sources.add(tool[len(QUERY_PREFIX):]) + tables.update(table.rsplit(".", 1)[-1] for table in sql_tables(sql)) + return sorted(sources), sorted(tables) + + +def upstream_pins(graph: Any) -> list[dict[str, Any]]: + """图里固定了上游版本的节点(子工作流、转抄别处的口径卡):[{node_id, kind, workflow_id, version}],按节点 id 排。 + + 固定的一版就是这一版的依赖之一:发布依据要把它写下来,之后那一边退役/改版时才知道牵动了谁。 + """ + from app.apps.versions import pinned_upstream + from app.engine.schema import GraphSpec + + try: + spec = GraphSpec.model_validate(graph or {}) + except Exception: # noqa: BLE001 - 图不成形:依赖这一段留空,图本身另有校验拦 + return [] + out: list[dict[str, Any]] = [] + for node in spec.nodes: + pin = pinned_upstream(node) + if pin is None: + continue + kind, workflow_id, version = pin + out.append({"node_id": node.id, "kind": kind, "workflow_id": workflow_id, "version": version}) + return sorted(out, key=lambda item: item["node_id"]) + + +def parameters_of(graph: Any) -> list[dict[str, Any]]: + """这一版的参数契约:入口字段按声明顺序(app/ledger/params.contract,各入口同一份)。""" + from app.ledger import params + from app.ledger.derive import entry_fields + + return params.contract(entry_fields(graph or {})) + + +# -------------------------------------------------------------------------- +# 每张卡的依据:验证记录 + 审阅决定 +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class CardBasis: + """一张源头口径卡在这一版上的依据:定义/绑定/取数语义指纹 + 引用的验证记录与审阅决定 + 齐不齐。""" + + card_id: str + title: str + caliber: str + caliber_version: str + metric_ids: tuple[str, ...] = () + definition_hash: str = "" + semantic_hash: str = "" + binding_fingerprints: dict[str, str] = field(default_factory=dict) + binding_status: str = "" + #: 引用的验证记录与审阅决定(就是清单里的那两段;没有覆盖这一版的记录时是 None) + record: dict[str, Any] | None = None + review: dict[str, Any] | None = None + ok: bool = False + code: str | None = None + reason: str | None = None + + def as_dict(self) -> dict[str, Any]: + """清单内容里这一张卡的那一段(工件、事件行的 cards 都是这一份)。""" + return {"card_id": self.card_id, "title": self.title, "caliber": self.caliber, + "caliber_version": self.caliber_version, "metric_ids": list(self.metric_ids), + "definition_hash": self.definition_hash, "semantic_hash": self.semantic_hash, + "binding_fingerprints": dict(self.binding_fingerprints), "binding_status": self.binding_status, + "validation": dict(self.record) if self.record else None, + "review": dict(self.review) if self.review else None, + "proof": {"ok": bool(self.ok), "code": self.code, "reason": self.reason, + **({} if self.ok else {"message": CODE_TEXT.get(str(self.code), "")})}} + + +def _card_base(graph: Any, card_id: str, *, workflow_id: str) -> CardBasis: + """一张卡的指纹部分(不含记录/审阅):定义、绑定、取数语义、指标清单、绑定状态。卡的名字也按图取。""" + from app.ledger import bindings, validation + + info = next((card for card in source_cards(graph) if card["id"] == card_id), {}) + materials = validation.materials(graph, card_id, workflow_id=workflow_id) + metrics = validation.card_metrics(graph, card_id) + try: + binding_status = str(bindings.analyze(graph, card_id).status) + except Exception: # noqa: BLE001 - 绑定状态算不出来不该让发布没依据,照实留空 + binding_status = "" + return CardBasis(card_id=card_id, title=str(info.get("title") or card_id), + caliber=str(info.get("caliber") or ""), caliber_version=str(info.get("caliber_version") or ""), + metric_ids=tuple(str(m["id"]) for m in metrics), + definition_hash=str(materials["definition_hash"]), + semantic_hash=str(materials["semantic_hash"]), + binding_fingerprints={str(k): str(v) for k, v in materials["binding_fingerprints"].items()}, + binding_status=binding_status) + + +def record_reference(record: Any) -> dict[str, Any]: + """清单里对 ValidationRecord 的那一段引用:绑定的依据、结论、范围、方法版本、运行引用。""" + return {"record_id": str(getattr(record, "id", "")), + "revision": int(getattr(record, "version", 0) or 0), + "status": str(getattr(record, "status", "") or ""), + "metric_ids": [str(m) for m in getattr(record, "metric_ids", None) or []], + "definition_hash": str(getattr(record, "definition_hash", "") or ""), + "binding_fingerprints": {str(k): str(v) for k, v in (getattr(record, "binding_fingerprints", None) or {}).items()}, + "semantic_hash": str(getattr(record, "semantic_hash", "") or ""), + "execution_hash": str(getattr(record, "execution_hash", "") or ""), + "method_version": int(getattr(record, "method_version", 0) or 0), + "expectation_source": str(getattr(record, "expectation_source", "") or ""), + "expectation_hash": str(getattr(record, "expectation_hash", "") or ""), + "inputs_hash": str(getattr(record, "inputs_hash", "") or ""), + "run_id": str(getattr(record, "run_id", "") or "")} + + +def review_reference(decision: Any) -> dict[str, Any]: + """清单里对 ReviewDecision 的那一段引用:决定、确认范围、所审依据、是不是认证主体做的。 + + **不写审批人和时间**:actor 是审阅那一行的属性,按 decision_id 去它那一行查;清单内容要能被重建,不能掺进会变的 + 东西(时间),也不能掺进身份(同一份依据换个人来确认,内容仍然只是「这份依据被确认了」)。 + """ + return {"decision_id": str(getattr(decision, "id", "")), + "decision": str(getattr(decision, "decision", "") or ""), + "scope": [str(m) for m in getattr(decision, "scope", None) or []], + "verified": bool(getattr(decision, "verified", False)), + "basis": {str(k): v for k, v in (getattr(decision, "basis", None) or {}).items()}} + + +def authenticated(decision: Any) -> bool: + """这条审阅决定算不算「认证主体做出的」:主体认证过,或者这套部署压根没开登录(那时身份由部署模式决定, + K05 照实记 verified=False,但服务端主体就是权威)。""" + if bool(getattr(decision, "verified", False)): + return True + from app.auth import current_mode + + return current_mode() == "off" + + +async def _records_for(session: Any, *, workflow_id: str, card_id: str) -> list[Any]: + """这张卡在这个工作流上的验证记录,新的在前。""" + from app.db.models import CaliberValidationRecord + + rows = await session.execute(select(CaliberValidationRecord).where( + CaliberValidationRecord.workflow_id == workflow_id, + CaliberValidationRecord.card_id == card_id).order_by( + CaliberValidationRecord.created_at.desc(), CaliberValidationRecord.id.desc())) + return list(rows.scalars()) + + +async def _latest_decision(session: Any, record_id: str) -> Any: + """这条验证记录上最新的一次审阅决定(读整行:要按它自己的依据和范围判)。写的时候只追加,取最后一条。""" + from app.db.models import CaliberReviewDecision + + return (await session.execute( + select(CaliberReviewDecision).where(CaliberReviewDecision.record_id == str(record_id)) + .order_by(CaliberReviewDecision.created_at.desc(), CaliberReviewDecision.id.desc()).limit(1)) + ).scalar_one_or_none() + + +def _judge_pair(base: CardBasis, *, record: Any, decision: Any, current: Mapping[str, Any]) -> CardBasis: + """一份记录 + 它的审阅决定够不够当这一版的依据(不足就在 code/reason 里说清是哪一种)。""" + from app.ledger import review as review_mod, validation + + if record is None: + return replace(base, code=RECORD_MISSING, reason="这一版没有留下验证记录:先试运行一次并给出独立期望") + if not validation.covers_current(record, current=current): + return replace(base, code=RECORD_STALE, reason="这一版现有的验证记录都不是对着它现在的定义和绑定做的:" + "定义、取数或绑定改过,请重新试运行并把期望给全") + if str(getattr(record, "status", "")) != validation.MATCHED: + return replace(base, code=RECORD_NOT_MATCHED, + reason=f"这一版最新的记录是「{getattr(record, 'status', '')}」:" + "要「有独立期望、逐条对得上」的 matched 记录才能算依据") + if decision is None: + return replace(base, code=REVIEW_MISSING, reason="这一版的验证记录还没有经过审阅确认:匹配不等于批准") + if not review_mod.covers_current(decision, current=current): + return replace(base, code=REVIEW_STALE, reason="这条审阅决定绑的是改之前的定义或绑定,不算覆盖这一版") + if str(getattr(decision, "decision", "")) != review_mod.CONFIRMED: + return replace(base, code=REVIEW_REJECTED, reason="这一版的验证记录被审阅驳回了") + if not authenticated(decision): + return replace(base, code=REVIEW_UNVERIFIED, reason="这条审阅决定不是认证主体做的(关登录时的自报署名不算)") + covered = [str(m) for m in getattr(record, "metric_ids", None) or []] + scope = [str(m) for m in getattr(decision, "scope", None) or []] + missing = [mid for mid in covered if mid not in scope] + if missing: + return replace(base, code=REVIEW_PARTIAL, + reason=f"审阅只确认了 {len(scope)} 条,还有 {len(missing)} 条没被确认" + "(确认范围要盖住这份记录的全部指标才算整张卡被确认)") + return replace(base, record=record_reference(record), review=review_reference(decision), ok=True) + + +async def card_basis(session: Any, *, workflow_id: str, graph: Any, card_id: str, saved: Any = None) -> CardBasis: + """一张源头口径卡在这一版上的依据。 + + `saved` 不给(发布时):认这张卡的记录里**最新的那条覆盖当前定义/绑定/取数语义的**(K05 的卡级结论按的就是它: + 之后又试运行过一次、那一次不是 matched,说明最新一次核对的结论就不是「对得上」,不能拿更早的那条顶上),再看它 + 有没有认证确认盖住全部指标的审阅决定。`saved` 给了(正式用途核对发布事件时):只认清单里引用的那一对记录/审阅 + ——**不在那时候另挑更新的记录**,不然「发布依据」就成了随时可以补的后门;引用的行不在了就明确说原始输入缺失。 + """ + from app.db.models import CaliberReviewDecision, CaliberValidationRecord + from app.ledger import review as review_mod, validation + + base = _card_base(graph, card_id, workflow_id=workflow_id) + current = {"workflow_id": workflow_id, "card_id": card_id, "definition_hash": base.definition_hash, + "binding_fingerprints": dict(base.binding_fingerprints), "semantic_hash": base.semantic_hash} + if saved is not None: + if (str(saved.get("definition_hash") or "") != base.definition_hash + or str(saved.get("semantic_hash") or "") != base.semantic_hash + or dict(saved.get("binding_fingerprints") or {}) != dict(base.binding_fingerprints)): + return replace(base, code=BASIS_MISMATCH, + reason="这份发布清单和这一版现在的定义/绑定对不上:不拿它证明这一版") + proof = saved.get("proof") if isinstance(saved.get("proof"), Mapping) else {} + ref = saved.get("validation") if isinstance(saved.get("validation"), Mapping) else None + if not proof.get("ok") or ref is None: + return replace(base, code=str(proof.get("code") or RECORD_MISSING), + reason=str(proof.get("reason") or CODE_TEXT.get(str(proof.get("code")), ""))) + record = await session.get(CaliberValidationRecord, str(ref.get("record_id") or "")) + decision = await session.get(CaliberReviewDecision, str((saved.get("review") or {}).get("decision_id") or "")) + if record is None or decision is None: + return replace(base, code=INPUTS_MISSING, reason=CODE_TEXT[INPUTS_MISSING]) + return _judge_pair(base, record=record, decision=decision, current=current) + records = await _records_for(session, workflow_id=workflow_id, card_id=card_id) + if not records: + return replace(base, code=RECORD_MISSING, reason=CODE_TEXT[RECORD_MISSING]) + covering = [row for row in records if validation.covers_current(row, current=current)] + if not covering: + return replace(base, code=RECORD_STALE, reason=CODE_TEXT[RECORD_STALE]) + record = covering[0] + return _judge_pair(base, record=record, decision=await _latest_decision(session, record.id), current=current) + + +async def basis_for(session: Any, *, workflow_id: str, graph: Any) -> list[CardBasis]: + """这一版每张源头口径卡的依据(发布时算,也用于「需不需要证明」)。""" + return [await card_basis(session, workflow_id=workflow_id, graph=graph, card_id=card["id"]) + for card in source_cards(graph)] + + +async def saved_basis(session: Any, *, workflow_id: str, graph: Any, content: Mapping[str, Any], + card_ids: Sequence[str] | None = None) -> list[CardBasis]: + """正式用途核对发布事件时这一版每张源头口径卡的依据:**只认清单内容**——逐张卡读清单里引用的那一对记录与审阅。 + + 比的一律是**工件内容**(read() 读出来那一份),不是可变的事件行列。清单里没有这张卡时按 BASIS_MISMATCH 判, + **不在这时候去库里另挑一条记录顶上**(发布依据只能在发布那一刻定下来,另外挑就是给它留一个随时可补的后门)。 + `card_ids` 给了就只判这几张(转抄卡递归判上游那一张卡时用),不给就是图里全部源头口径卡。老资产(这一版没有 + 发布事件)不走这里:调用方先判 publication is None。 + """ + stored = {str(card.get("card_id")): card for card in (content.get("cards") or []) if isinstance(card, Mapping)} + wanted = None if card_ids is None else {str(cid) for cid in card_ids} + out: list[CardBasis] = [] + for card in source_cards(graph): + card_id = str(card["id"]) + if wanted is not None and card_id not in wanted: + continue + saved = stored.get(card_id) + if saved is None: + base = _card_base(graph, card_id, workflow_id=workflow_id) + out.append(replace(base, code=BASIS_MISMATCH, + reason="发布清单里没有这张源头口径卡:这一版没有它的发布依据")) + continue + out.append(await card_basis(session, workflow_id=workflow_id, graph=graph, card_id=card_id, saved=saved)) + return out + + +def manifest_problem(manifest: Any, *, graph: Any) -> dict[str, Any] | None: + """这份清单是不是**这一版这一张图**的清单:图指纹对不上(错图)、清单里没有图上的某张源头口径卡(缺卡) + 都交回一条版本级的 problem(code=BASIS_MISMATCH),对上了交回 None。 + + `manifest` 给**清单内容**(工件读出来的那一份)——比的一律是工件,不认可变的事件行列;给事件行时这里自己读一遍 + 工件(读不出来就按那条机器码交回;调用方已经读过就把内容传进来,别读两遍)。发布依据只能在发布那一刻定下来, + 所以这里**不补**:缺的那张卡不去库里另挑一条记录顶上,错图也不拿别的版本顶。老资产(这一版没有发布事件)不走 + 这里——调用方先判 publication is None,保持原行为。 + """ + from app.core.artifact_store import graph_hash + + content = manifest if isinstance(manifest, Mapping) else None + if content is None: + content, problems = verified_content(manifest) + if content is None: + return problems[0] if problems else None + fixed = graph if isinstance(graph, Mapping) else {} + if str(content.get("graph_hash") or "") != graph_hash(fixed): + return {"card_id": "", "code": BASIS_MISMATCH, + "message": "这一版的发布清单不是这一张图的清单(图指纹对不上):不拿它证明这一版", + "reason": "这一版的发布清单不是这一张图的清单"} + stored = {str(card.get("card_id")) for card in (content.get("cards") or []) if isinstance(card, Mapping)} + for card in source_cards(fixed): + if str(card["id"]) in stored: + continue + return {"card_id": str(card["id"]), "code": BASIS_MISMATCH, + "message": f"发布清单里没有这一版图上的源头口径卡「{card['title']}」:这张卡没有发布依据", + "reason": "发布清单没有覆盖这一版图上的每一张源头口径卡:缺的那张不在这时候另挑记录补"} + return None + + +# -------------------------------------------------------------------------- +# 转抄卡(caliber_from):上游那一张卡按同一个用途递归判 +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class Chained: + """转抄卡递归判上游的结果:上游这一版要不要证明、以及翻成下游看得见的形状的问题。""" + + required: bool = False + problems: tuple[dict[str, Any], ...] = () + + +def chained_nodes(graph: Any) -> list[dict[str, Any]]: + """图里转抄别处口径的卡(metrics 节点带 caliber_from):[{node_id, title, config, workflow_id, version, card_id}], + 按节点在图里的先后。 + + 引用不完整(缺工作流、缺卡、版本号不是正整数)的跳过:那是发布门禁(schema 的 caliber_from 检查报 error)和 + 运行时各自的活,不是发布依据这一层的事。 + """ + from app.apps.tree import node_map + + out: list[dict[str, Any]] = [] + for node_id, node in node_map(graph).items(): + if node.get("type") != "metrics": + continue + ref = (node.get("config") or {}).get("caliber_from") + if not isinstance(ref, Mapping): + continue + raw = ref.get("workflow_version") + if not str(ref.get("workflow_id") or "") or not str(ref.get("node_id") or "") \ + or isinstance(raw, bool) or not str(raw or "").isdigit() or int(raw) < 1: + continue + out.append({"node_id": node_id, "title": str(node.get("title") or node_id), + "config": dict(node.get("config") or {}), + "workflow_id": str(ref["workflow_id"]), "version": int(raw), + "card_id": str(ref["node_id"])}) + return out + + +def _version_required(workflow: Any, publication: Any) -> bool: + """这一版要不要证明:发布时要求过(事件行 required)或现在还接管着——和 requires_proof_for 同一条规则,只是不要求 + 「图里有源头口径卡」:转抄卡自己不是源头卡,它要证明是因为它引用的上游要。""" + return bool(getattr(publication, "required", False)) or bool(app_versions.taken_over(workflow)) + + +async def chained_problems(session: Any, *, graph: Any, purpose: str, + seen: set[tuple[str, int, str]] | None = None) -> Chained: + """图里每张转抄卡(caliber_from)固定引用的上游**那一张卡**:按同一个用途递归判它够不够。 + + 只在会按发布依据拦的用途(formal / issue)上判——试算、探索、组合一条都不受影响。只判被引用的那一张卡: + 上游工作流里别的卡与下游无关,不牵连。上游那一版没有发布事件(老资产)的**明确不升级**,保持原行为;循环引用 + (A 引 B、B 又引回 A)按「这一对已经判过」截断,不转圈。同一个上游被图上多处引用时只在第一处说(同一份问题说两遍 + 没有意义)。链子**每一层**的问题都保留(工件、编译器、覆盖,以及那一层自己要求证明时的依据),只有「链子上没有任何 + 一层要求证明」时一条都不报——那几层自己按 formal 发起也就是 formal_unproven(老资产、不在证明范围内),下游不另立 + 一套更严的说法。问题都翻成下游看得见的形状:机器码照旧(上游是什么码就是什么码)+ 上游引用与整条引用链,下游入口 + 照旧只认 problems[0]。 + """ + if purpose not in PROOF_PURPOSES: + return Chained() + seen = set() if seen is None else seen + required = False + problems: list[dict[str, Any]] = [] + for node in chained_nodes(graph): + made = await _pinned_card(session, node=node, purpose=purpose, seen=seen) + required = required or made.required + problems.extend(made.problems) + if not required: + return Chained() + return Chained(required=True, problems=tuple(problems)) + + +async def _pinned_card(session: Any, *, node: Mapping[str, Any], purpose: str, + seen: set[tuple[str, int, str]]) -> Chained: + """一个转抄卡节点固定引用的上游那一张卡:递归判(那张卡自己也是转抄卡时继续往下走一层)。 + + 这一层的工件/编译/覆盖问题、以及被引用那张卡自己的依据问题都在这里收着往上报,递归到哪一层都不丢:链子上谁坏了都 + 算这条链子过不了(上层正常也不能替下层顶)。node 可以是 `chained_nodes` 给的那一项,也可以是图里节点本身 + (`node_map` 那种形状)——两处都带 config。""" + from app.apps.tree import node_map + from app.db.models import Workflow + + node_id = str(node.get("node_id") or node.get("id") or "") + title = str(node.get("title") or node_id) + ref = (node.get("config") or {}).get("caliber_from") + if not isinstance(ref, Mapping): + return Chained() + workflow_id, card_id = str(ref.get("workflow_id") or ""), str(ref.get("node_id") or "") + raw = ref.get("workflow_version") + if not workflow_id or not card_id or isinstance(raw, bool) or not str(raw or "").isdigit() or int(raw) < 1: + return Chained() + version = int(raw) + key = (workflow_id, version, card_id) + if key in seen: + return Chained() + seen.add(key) + workflow = await session.get(Workflow, workflow_id) + row = await app_versions.version_row(session, workflow_id, version) + if workflow is None or row is None: + return Chained() # 上游不在:「固定那一版必须已发布」在发起时另有门禁,运行时也响亮失败 + publication = await latest(session, workflow_id, version) + if publication is None: + return Chained() # 老资产(那一版没有发布事件):明确不升级,保持原行为 + upstream_graph = row.graph if isinstance(row.graph, Mapping) else {} + content, problems = verified_content(publication) + if content is not None and (coverage := manifest_problem(content, graph=upstream_graph)) is not None: + problems = (*problems, coverage) + if card_id in {str(card["id"]) for card in source_cards(upstream_graph)}: + required = _version_required(workflow, publication) + if required and content is not None: + basis = (await saved_basis(session, workflow_id=workflow_id, graph=upstream_graph, content=content, + card_ids=[card_id]))[0] + problems = (*problems, *basis_problems([basis])) + else: + # 被引用的那张卡自己也是转抄卡:继续往下走一层——这一层的工件/编译/覆盖问题照旧带着往上报(上层正常也不能替 + # 下层顶:M 的清单删了、S 这边再齐也不作数),要证明与否由链子整体定(chained_problems 那一层判)。引用指不到 + # 图上的节点(nested_node 为空)时同样保留这一层的问题,只是往下没有可判的了 + nested_node = node_map(upstream_graph).get(card_id) + nested = (await _pinned_card(session, node=nested_node, purpose=purpose, seen=seen) + if isinstance(nested_node, Mapping) else Chained()) + required = _version_required(workflow, publication) or nested.required + problems = (*problems, *nested.problems) + return Chained(required=required, problems=tuple(_traced(problems, node_id=node_id, title=title, + upstream_workflow=workflow, upstream_version=version, + upstream_card=card_id))) + + +def _traced(problems: Sequence[Mapping[str, Any]], *, node_id: str, title: str, upstream_workflow: Any, + upstream_version: int, upstream_card: str) -> list[dict[str, Any]]: + """把上游的问题翻成下游这一环看得见的形状:机器码照旧,点名下游的节点(可追踪),附上上游引用与整条引用链。 + + `trace` 从下游这一环往下排(这一环的引用在最前、出问题的那一层在最后):链子上每层的问题都各自保留,去重按 + 「下游的哪张卡 + 机器码 + 整条引用链」来,不同层不会被合成一条。 + """ + hop = {"node_id": node_id, "workflow_id": str(getattr(upstream_workflow, "id", "")), + "version": int(upstream_version), "card_id": upstream_card} + name = str(getattr(upstream_workflow, "name", "") or getattr(upstream_workflow, "id", "")) + out: list[dict[str, Any]] = [] + for problem in problems: + said = str(problem.get("message") or problem.get("reason") or CODE_TEXT.get(str(problem.get("code")), "")) + inner = [dict(item) for item in (problem.get("trace") or []) if isinstance(item, Mapping)] + out.append({**dict(problem), "card_id": node_id, + "message": f"「{title}」转抄的「{name}」v{upstream_version} 的口径卡「{upstream_card}」过不了发布依据:" + f"{said}", + "upstream": dict(hop), "trace": [dict(hop), *inner]}) + return out + + +def problem_key(problem: Mapping[str, Any]) -> tuple[str, str, tuple[tuple[str, int, str], ...]] | None: + """一条问题的去重键:下游的哪张卡 + 机器码 + 整条引用链(到出问题的那一层)。 + + 版本级那些(工件、编译器、错图,`card_id` 为空)没有键——逐条留着(编译器的问题是逐项给的)。没有键或者键没见过 + 就都算一条,同一件事说两遍才合成一条(覆盖那条点名到某张卡、逐卡判出来同一条)。""" + card_id = str(problem.get("card_id") or "") + if not card_id: + return None + trace = tuple((str(hop.get("workflow_id") or ""), int(hop.get("version") or 0), str(hop.get("card_id") or "")) + for hop in problem.get("trace") or [] if isinstance(hop, Mapping)) + return (card_id, str(problem.get("code") or ""), trace) + + +# -------------------------------------------------------------------------- +# 内容与工件 +# -------------------------------------------------------------------------- + + +def build_content(*, workflow_id: str, version: int, level: str, graph: Any, cards: Sequence[CardBasis]) -> dict[str, Any]: + """这一版的清单内容:**只由原始输入决定**(这一版不可变的图 + 每张卡引用的那两行记录的值)。""" + from app.core.artifact_store import execution_hash, graph_hash + + sources, tables = fetch_dependencies(graph) + return { + "format": FORMAT, + "workflow_id": str(workflow_id), + "version": int(version), + "level": str(level or ""), + "graph_hash": graph_hash(graph or {}), + "execution_hash": execution_hash(graph or {}), + "compiler": compiler_versions(), + "cards": [card.as_dict() for card in cards], + "parameters": parameters_of(graph), + "dependencies": {"sources": sources, "tables": tables, "upstream": upstream_pins(graph)}, + } + + +def content_hash(content: Mapping[str, Any]) -> str: + """清单内容的内容哈希(= 工件 id,也是事件行上的 manifest)。""" + from app.core.artifact_store import canonical_json, content_hash as hash_of + + return hash_of(canonical_json(content)) + + +def cards_summary(cards: Sequence[CardBasis]) -> list[dict[str, Any]]: + return [card.as_dict() for card in cards] + + +def basis_problems(cards: Sequence[CardBasis]) -> list[dict[str, Any]]: + """依据缺哪一块:[{card_id, code, message, reason}],齐了就是空。""" + return [{"card_id": card.card_id, "code": card.code, "message": card.reason or CODE_TEXT.get(str(card.code), ""), + "reason": card.reason} for card in cards if not card.ok] + + +def basis_rows(stored: Any) -> list[dict[str, Any]]: + """事件行上记下的那几段依据摘要 → 「缺哪一块」:[{card_id, code, message}],齐了就是空。 + + 读的是事件行(`cards` 列,和清单内容里的那一份逐字相同),不读工件:版本详情、列表这类接口要的是「齐不齐」, + 不是整份清单。 + """ + out: list[dict[str, Any]] = [] + for card in stored or []: + if not isinstance(card, Mapping): + continue + proof = card.get("proof") if isinstance(card.get("proof"), Mapping) else {} + if proof.get("ok"): + continue + code = str(proof.get("code") or RECORD_MISSING) + out.append({"card_id": str(card.get("card_id") or ""), "code": code, + "message": str(proof.get("reason") or proof.get("message") or CODE_TEXT.get(code, ""))}) + return out + + +async def observe(session: Any, *, workflow: Any, snapshot: Any, catalog: Any = None, schema: Any = None, + capabilities: Any = None) -> dict[str, Any]: + """发布这一刻**观察到**的环境:目录/结构/能力版本、绑定的工具现在在不在。 + + 这些不进清单内容的哈希(它们随环境变,清单要能被重建),单独记在事件行上,读的人知道当时是什么样子。 + 目录/结构/能力版本由调用方(commit_publish 已经算好的那几份)传进来:这里不再查一遍,也不碰版本行上还没提交的写。 + """ + from app.db.base import utcnow + + missing: list[dict[str, str]] = [] + try: + from app.engine.launch import missing_tools + from app.engine.schema import GraphSpec + + spec = GraphSpec.model_validate(snapshot.graph or {}) + missing = [{"who": who, "tool": tool, "where": where} for who, tool, where in + await missing_tools(session, spec)] + except Exception: # noqa: BLE001 - 图不成形/工具表读不出来:观察这一项留空,发布本身另有校验 + missing = [] + return {"at": utcnow().isoformat(), + "catalog_versions": dict(catalog if catalog is not None else snapshot.catalog_versions or {}), + "schema_versions": dict(schema if schema is not None else snapshot.schema_versions or {}), + "capability_versions": dict(capabilities if capabilities is not None + else snapshot.capability_versions or {}), + "missing_tools": missing} + + +async def publish(session: Any, *, workflow: Any, snapshot: Any, level: str, actor: str | None, + observed: Mapping[str, Any] | None = None) -> dict[str, Any]: + """发布这一刻的依据:算出内容、存成不可变清单工件、追加一行发布事件。**不提交**(和发布那几列同一个事务)。 + + 调用方(api/workflows.commit_publish)先做完读(能力版本、目录版本),再调这里:工件是另一个会话按内容寻址写的, + 这边手里还没有未提交的写,不会两个会话抢同一把写锁。 + """ + from app.core.artifact_store import put_json + from app.db.models import WorkflowPublication + + graph = snapshot.graph or {} + cards = await basis_for(session, workflow_id=workflow.id, graph=graph) + content = build_content(workflow_id=workflow.id, version=int(snapshot.version), level=level, graph=graph, + cards=cards) + manifest = await put_json(content, kind=KIND, run_id=None, meta={ + "workflow_id": workflow.id, "version": int(snapshot.version), "level": level, + "cards": [card.card_id for card in cards], "manifest_version": MANIFEST_VERSION}) + required = requires_proof_for(workflow, cards) + row = WorkflowPublication( + workflow_id=workflow.id, version=int(snapshot.version), level=level, graph_hash=content["graph_hash"], + manifest=manifest, format=FORMAT, cards=cards_summary(cards), + proven=bool(cards) and not basis_problems(cards), required=required, + observed=dict(observed) if observed is not None else await observe(session, workflow=workflow, snapshot=snapshot), + actor=actor) + session.add(row) + await session.flush() + return {"id": row.id, "workflow_id": workflow.id, "version": int(snapshot.version), "level": level, + "manifest": manifest, "format": FORMAT, "cards": cards_summary(cards), + "proven": bool(row.proven), "required": required, "problems": basis_problems(cards), + "observed": dict(row.observed or {})} + + +# -------------------------------------------------------------------------- +# 读:清单、事件、重建 +# -------------------------------------------------------------------------- + + +class PublicationUnreadable(ValueError): + """这份发布依据读不出来 / 重建不上:code 是机器码,message 给人看。""" + + def __init__(self, message: str, code: str) -> None: + super().__init__(message) + self.message = message + self.code = code + + +async def latest(session: Any, workflow_id: str, version: int) -> Any | None: + """某一版最近一次发布留下的那行事件(重发旧版就是最新那一行);没有就是 None(老资产或没发布过)。""" + from app.db.models import WorkflowPublication + + return (await session.execute( + select(WorkflowPublication).where(WorkflowPublication.workflow_id == str(workflow_id), + WorkflowPublication.version == int(version)) + .order_by(WorkflowPublication.created_at.desc(), WorkflowPublication.id.desc()).limit(1))).scalar_one_or_none() + + +async def events(session: Any, workflow_id: str, version: int | None = None) -> list[Any]: + """这个工作流(这一版)全部发布事件,新的在前。旧事件和旧清单不改写,这里能看到重发了几次。""" + from app.db.models import WorkflowPublication + + stmt = select(WorkflowPublication).where(WorkflowPublication.workflow_id == str(workflow_id)) + if version is not None: + stmt = stmt.where(WorkflowPublication.version == int(version)) + rows = await session.execute(stmt.order_by(WorkflowPublication.created_at.desc(), WorkflowPublication.id.desc())) + return list(rows.scalars()) + + +def read(publication: Any) -> dict[str, Any]: + """读一份发布清单(按内容寻址的工件,读的时候复验哈希)。读不出来、被改过、不是这一份都抛 PublicationUnreadable。""" + from app.core.artifact_store import load + + if publication is None: + raise PublicationUnreadable("这一版没有发布清单(发布事件之前发布的老资产)", BASIS_MISSING) + artifact = str(getattr(publication, "manifest", "") or "") + try: + content = load(artifact) + except ValueError as e: # 内容与哈希不符:工件被改过 + raise PublicationUnreadable(f"发布清单与它的哈希不符,疑似被修改:{e}", MANIFEST_TAMPERED) from e + if content is None: + raise PublicationUnreadable(f"发布清单工件不在了({artifact[:12]}…):文件缺失或被回收", MANIFEST_MISSING) + if not isinstance(content, dict) or content.get("format") != FORMAT \ + or str(content.get("workflow_id")) != str(getattr(publication, "workflow_id", "")) \ + or int(content.get("version") or 0) != int(getattr(publication, "version", 0) or 0): + raise PublicationUnreadable("这份工件不是这一版这一份发布清单", MANIFEST_FOREIGN) + if content_hash(content) != artifact: + raise PublicationUnreadable("发布清单的内容哈希与工件 id 不符", MANIFEST_TAMPERED) + return content + + +def verified_content(publication: Any) -> tuple[dict[str, Any] | None, tuple[dict[str, Any], ...]]: + """读一份发布清单并核**工件本身**:内容哈希复验、就是这一版这一份、编译器约定现在这一套认不认。 + + 和 K09 的固定执行(ledger/querycore 的 `_verified_manifest`)是同一份核对:正式用途每次执行都要复验,工件被删、 + 被改过、不是这一版这一份、按别的约定物化的,一律不能继续正式执行。交回 (内容, 问题):读不出来时内容是 None, + 问题里带 read() 那条机器码;编译器约定不认时内容照旧交回(读的人还能看它是按哪一套物化的),问题逐项给 + COMPILER_MISMATCH / COMPILER_MISSING。老资产(这一版没有发布事件)不走这里——调用方先判 publication is None。 + """ + try: + content = read(publication) + except PublicationUnreadable as e: + return None, ({"card_id": "", "code": str(e.code), "message": e.message, "reason": e.message},) + problems = tuple({"card_id": "", "code": str(problem.get("code") or COMPILER_MISMATCH), + "key": str(problem.get("key") or ""), + "message": str(problem.get("message") or ""), + "reason": str(problem.get("message") or "")} + for problem in compiler_problems(content)) + return content, problems + + +async def rebuild(session: Any, publication: Any) -> dict[str, Any]: + """按原始输入把这份清单重建一遍:**内容一字不差才算「可重建」**。 + + 原始输入是这一版不可变的图和清单里引用的那两行记录。缺任何一样(版本行被删、引用的记录/审阅不在、工件不在)都抛 + PublicationUnreadable,明确失败,不猜、不拿别的版本顶。回来的是 {content, manifest, matches, problems}。 + """ + from app.db.models import CaliberReviewDecision, CaliberValidationRecord + + content = read(publication) + graph = await _graph_of(session, publication, expect=content) + problems: list[dict[str, Any]] = [] + cards: list[CardBasis] = [] + stored = {str(card.get("card_id")): card for card in (getattr(publication, "cards", None) or []) + if isinstance(card, Mapping)} + for card in content.get("cards") or []: + if not isinstance(card, Mapping): + continue + card_id = str(card.get("card_id") or "") + saved = stored.get(card_id) or card + ref = card.get("validation") if isinstance(card.get("validation"), Mapping) else None + decision_ref = card.get("review") if isinstance(card.get("review"), Mapping) else None + if ref is not None: + record = await session.get(CaliberValidationRecord, str(ref.get("record_id") or "")) + if record is None: + raise PublicationUnreadable( + f"清单引用的验证记录不在了(口径卡 {card_id}):原始输入缺失,重建不上", INPUTS_MISSING) + if record_reference(record) != dict(ref): + problems.append({"card_id": card_id, "code": BASIS_MISMATCH, "message": "验证记录变了"}) + if decision_ref is not None: + decision = await session.get(CaliberReviewDecision, str(decision_ref.get("decision_id") or "")) + if decision is None: + raise PublicationUnreadable( + f"清单引用的审阅决定不在了(口径卡 {card_id}):原始输入缺失,重建不上", INPUTS_MISSING) + if review_reference(decision) != dict(decision_ref): + problems.append({"card_id": card_id, "code": BASIS_MISMATCH, "message": "审阅决定变了"}) + made = await card_basis(session, workflow_id=str(publication.workflow_id), graph=graph, card_id=card_id, + saved=saved) + if (made.definition_hash != str(card.get("definition_hash") or "") + or made.semantic_hash != str(card.get("semantic_hash") or "") + or dict(made.binding_fingerprints) != dict(card.get("binding_fingerprints") or {}) + or list(made.metric_ids) != [str(m) for m in card.get("metric_ids") or []]): + problems.append({"card_id": card_id, "code": BASIS_MISMATCH, "message": "这张卡的定义/绑定与清单不符"}) + cards.append(made) + made_content = build_content(workflow_id=str(publication.workflow_id), version=int(publication.version), + level=str(publication.level or ""), graph=graph, cards=cards) + digest = content_hash(made_content) + manifest = str(getattr(publication, "manifest", "") or "") + return {"content": made_content, "original": content, "manifest": manifest, "computed": digest, + "matches": digest == manifest and not problems, "problems": problems} + + +async def _graph_of(session: Any, publication: Any, *, expect: Mapping[str, Any]) -> dict[str, Any]: + """这份清单对着的那一版图(原始输入之一)。不在时明确失败。""" + from app.apps.versions import version_row + + row = await version_row(session, str(publication.workflow_id), int(publication.version)) + if row is None or not isinstance(row.graph, dict) or not row.graph: + raise PublicationUnreadable( + f"这一版({publication.workflow_id} v{publication.version})的图不在了:原始输入缺失,重建不上", INPUTS_MISSING) + from app.core.artifact_store import graph_hash + + if str(expect.get("graph_hash") or "") and graph_hash(row.graph) != str(expect["graph_hash"]): + raise PublicationUnreadable("这一版现在的图和清单里固定的图指纹对不上", BASIS_MISMATCH) + return row.graph + + +# -------------------------------------------------------------------------- +# 版本解析:推荐版 / 最高版 / 显式版 +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class Resolved: + """一次默认调用解析到的版本。explicit=True 表示调用方点名了版本(始终固定到它)。""" + + workflow_id: str + version: int + row: Any + explicit: bool + recommended: int | None = None + latest: int | None = None + publication: Any | None = None + #: 清单工件读出来的内容(read() 复验过的那一份):正式用途的逐卡核对也按它,不按可变的事件行列 + publication_content: dict[str, Any] | None = None + #: 清单工件本身的问题(不在/被改过/不是这一版这一份、编译器约定不认):和哪张图无关,空就是没问题 + publication_problems: tuple[dict[str, Any], ...] = () + #: 清单和这一版这一张图对不上的那一条(错图/缺卡):按版本行的图核的,正式用途按自己手里那张图再核一遍 + publication_coverage: dict[str, Any] | None = None + upgrade: dict[str, Any] | None = None + + @property + def publication_problem(self) -> dict[str, Any] | None: + """第一条问题:工件/编译器在前、覆盖在后——和正式用途拒绝时先说的那一条同一个顺序。没有问题是 None。""" + return self.publication_problems[0] if self.publication_problems else self.publication_coverage + + +async def recommended(session: Any, workflow: Any) -> Any | None: + """这份资产当前推荐的发布版(Workflow.published_version 指的那一版):**默认调用读它**。 + + 目录、look、账本挑候选都按这里解析。「最新的那一版」是另一回事(apps/versions.latest_published,只用于升级发现)。 + 推荐指针为空、或者指的那一版查不出来时返回 None;指针指着一条已经查不到的版本行时退回最高已发布版, + 不猜别的版本。 + """ + if workflow is None or not getattr(workflow, "published_version", None): + return None + row = await app_versions.version_row(session, workflow.id, int(workflow.published_version)) + if row is not None and app_versions.is_published(row, current=workflow.published_version): + return row + return await app_versions.latest_published(session, workflow.id) + + +async def highest(session: Any, workflow_id: str) -> Any | None: + """最高已发布版(升级发现用):apps/versions.latest_published。""" + return await app_versions.latest_published(session, workflow_id) + + +async def resolve(session: Any, workflow: Any, *, version: int | None = None, purpose: str, + explicit: bool | None = None) -> Resolved | None: + """按用途解析要用的版本:给了 version 就固定到它(显式请求始终固定);没给就读推荐版。 + + `explicit` 是**调用方有没有点名版本**:不给就按「给了 version 就是点名」推。调用方自己先解析一次、再把那一版交给 + 这里时时(engine/launch.launch_run 就是这么做的:默认发起只读一次推荐指针、之后一律按那一版走,并发下指针漂移也 + 只影响下一次发起)要显式传 explicit=False,运行来源里才不会把它记成「调用方点名的版本」。 + + purpose 由服务端入口常量决定(PURPOSES),这里只认它、不认客户端传的用途。读不出来(工作流没有推荐版、 + 指名的版本不在)返回 None,怎么拒绝由各入口按自己原来的说法说。 + + 这一版有发布事件时顺手核一遍清单(`verified_content`:工件复验 + 编译器约定;`manifest_problem`:是不是这一版 + 这一张图、缺不缺卡),结论放在 `publication_content` / `publication_problems` / `publication_coverage` 上—— + 读的人也看得见,正式用途按它拒。老资产(没有事件)都是空,保持原行为。 + """ + if purpose not in PURPOSES: + raise ValueError(f"不认识的用途:{purpose}") + if workflow is None: + return None + newest = await highest(session, workflow.id) + if version is None: + row = await recommended(session, workflow) + if row is None: + return None + else: + row = await app_versions.version_row(session, workflow.id, int(version)) + if row is None: + return None + publication = await latest(session, workflow.id, int(row.version)) + content: dict[str, Any] | None = None + problems: tuple[dict[str, Any], ...] = () + coverage: dict[str, Any] | None = None + if publication is not None: + content, problems = verified_content(publication) + if content is not None: + coverage = manifest_problem(content, graph=row.graph) + return Resolved(workflow_id=workflow.id, version=int(row.version), row=row, + explicit=(version is not None) if explicit is None else bool(explicit), + recommended=workflow.published_version, latest=newest.version if newest is not None else None, + publication=publication, publication_content=content, publication_problems=problems, + publication_coverage=coverage, upgrade=None) + + +async def upgrade_of(session: Any, workflow: Any) -> dict[str, Any] | None: + """有没有比推荐版更高的已发布版(升级发现:告诉人「有一版更新的」)。 + + 这里只**提示**,不替调用方换版本:默认调用读推荐版(可能是一个被重新推上去的旧版),更高的一版要不要升由 + 人决定。返回 {version, recommended, latest, reason},没有更高的就是 None。 + """ + if workflow is None or not getattr(workflow, "published_version", None): + return None + latest = await highest(session, workflow.id) + if latest is None or int(latest.version) <= int(workflow.published_version): + return None + return {"version": int(latest.version), "recommended": int(workflow.published_version), + "latest": int(latest.version), + "reason": f"「{getattr(workflow, 'name', '') or workflow.id}」还有一版更新的发布版 v{latest.version}" + f"(现在推荐的是 v{workflow.published_version})"} + + +# -------------------------------------------------------------------------- +# 用途判定:需不需要证明、证明齐不齐、这一版是什么身份 +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class Judged: + """一次正式用途判定的结果:解析到的版本、发布依据、需不需要证明、身份、以及不够时的机器码。""" + + purpose: str + workflow_id: str + version: int + explicit: bool + published: bool + publication: Any | None = None + requires_proof: bool = False + identity: str = LEGACY + cards: tuple[CardBasis, ...] = () + problems: tuple[dict[str, Any], ...] = () + upgrade: dict[str, Any] | None = None + recommended: int | None = None + latest: int | None = None + + @property + def proven(self) -> bool: + return self.requires_proof and not self.problems + + @property + def code(self) -> str | None: + """不够时的机器码(够了为空)。""" + return str(self.problems[0]["code"]) if self.problems else None + + @property + def refusal(self) -> tuple[str, str] | None: + """(机器码, 白话):正式用途拦下来时给入口用它原来的说法抛出去。""" + if not self.problems: + return None + first = self.problems[0] + return str(first["code"]), str(first.get("message") or CODE_TEXT.get(str(first["code"]), "")) + + def as_dict(self) -> dict[str, Any]: + """运行记录/接口里那一小段:实际用哪一版、哪份清单、什么身份。""" + return {"purpose": self.purpose, "version": self.version, "explicit": self.explicit, + "manifest": str(getattr(self.publication, "manifest", "") or "") or None, + "publication": str(getattr(self.publication, "id", "") or "") or None, + "identity": self.identity, "requires_proof": self.requires_proof, + "problems": [dict(p) for p in self.problems], + "upgrade": dict(self.upgrade) if self.upgrade else None} + + +def requires_proof_for(workflow: Any, cards: Sequence[CardBasis], publication: Any = None) -> bool: + """这份资产在这一版上要不要证明:图里有源头口径卡,而且**发布时要求过证明**(事件行上的 required)**或者现在还 + 接管着**(apps/versions.taken_over)——两者取或。 + + 发布那一刻的严格性记在事件行上(publish 写),之后把接管标记去掉(清 tags 之类)不会让已经按严格发的那些版本降级; + 反过来,发布之后才接管上的资产照旧要证明。老资产(这一版没有发布事件)不启用——保持原行为,只是记身份 + formal_legacy;不需要证明的记 formal_unproven。 + """ + return bool(cards) and (bool(getattr(publication, "required", False)) or bool(app_versions.taken_over(workflow))) + + +async def judge(session: Any, workflow: Any, *, version: int | None = None, purpose: str, + snapshot: Any = None, explicit: bool | None = None) -> Judged | None: + """正式用途的共用判定:解析版本、取发布依据、按用途说这一版够不够、身份是什么。 + + 只有 PURPOSES 里的用途能进来(purpose 由服务端入口常量决定)。formal / issue 之外的用途一样能读,但**不会因为 + 缺验证审阅被拦**——试算、探索、组合本来就不该拿正式口径的门禁去卡(A03)。 + + 这一版**有发布事件**时(老资产没有事件,保持原行为、身份 formal_legacy): + - 先核工件本身:`read()` 复验(工件不在、被改过、不是这一版这一份)与 `compiler_problems()`(按别的约定物化的 + 不按新规则重解释)——和 K09 的固定执行同一份核对,正式用途每次执行都核,过关才继续; + - 再核清单覆盖:图指纹对得上、图上每张源头口径卡都在清单里(错图/缺卡当场 BASIS_MISMATCH); + - 再逐张卡认清单里引用的那一对记录/审阅(不在核对的时候另挑更新的记录补,清单里没有的卡也不现场挑一条顶上); + - 再按同一用途递归判转抄卡(caliber_from)固定引用的上游那一张卡:上游要证明就得同样满足,失败按上游那条机器码 + + 上游引用拒(`chained_problems`)。 + requires_proof = 这一版自己要证明(事件行 required 或现在还接管着)或引用的上游要证明;这些都齐了才叫 + formal_proven,否则 formal_unproven。`explicit` 是调用方有没有点名版本(见 resolve),运行来源里照实记。 + + **权限和治理不在这里重判**:发起、出具各自的入口照旧按现有那一套判(角色、应用授权、治理 lint、每日上限), + 这里只判发布依据;用到的说法也都是现成的——is_published / retired、taken_over(接管)、K05 的覆盖判断。 + 版本行读不出来、没发布过、已退役这些**原来的拒绝**也不在这里说:各入口照旧按自己的说法拒(HTTP 语义不变), + 这里只在「发布依据不够/读不出来」时说。 + """ + resolved = await resolve(session, workflow, version=version, purpose=purpose, explicit=explicit) + if resolved is None: + return None + row = resolved.row + published = app_versions.is_published(row, current=getattr(workflow, "published_version", None)) \ + and getattr(row, "retired_at", None) is None + graph = (snapshot.graph if snapshot is not None else None) or getattr(row, "graph", None) or {} + cards: tuple[CardBasis, ...] = () + problems: list[dict[str, Any]] = [] + requires = False + identity = LEGACY + if published: + if resolved.publication is None: + identity = LEGACY + else: + # 工件/编译器(与哪张图无关)+ 覆盖(按这里要判的那张图再核一遍;resolve 上那份是给读的人看的) + content = resolved.publication_content + coverage = manifest_problem(content, graph=graph) if content is not None else None + version_problems = [*resolved.publication_problems, *([coverage] if coverage else [])] + own_required = False + if content is not None: + cards = tuple(await saved_basis(session, workflow_id=resolved.workflow_id, graph=graph, + content=content)) + own_required = requires_proof_for(workflow, cards, publication=resolved.publication) + chained = await chained_problems(session, graph=graph, purpose=purpose) + if purpose in PROOF_PURPOSES: + requires = own_required or chained.required + # 同一件事只说一条:覆盖那条点名到某张卡时,逐卡判出来的同一条不再重复;链子上不同层的问题各有各的 + # 引用链(problem_key),不会被合成一条 + problems = [] + spoken: set[tuple[str, str, tuple[tuple[str, int, str], ...]]] = set() + for found in [*version_problems, *(basis_problems(cards) if own_required else []), *chained.problems]: + key = problem_key(found) + if key is not None: + if key in spoken: + continue + spoken.add(key) + problems.append(found) + identity = PROVEN if (requires and not problems) else UNPROVEN + else: + requires = False + identity = UNPROVEN + return Judged(purpose=purpose, workflow_id=resolved.workflow_id, version=resolved.version, + explicit=resolved.explicit, published=published, + publication=resolved.publication if published else None, requires_proof=requires, + identity=identity, cards=cards, problems=tuple(problems), + upgrade=await upgrade_of(session, workflow), recommended=resolved.recommended, + latest=resolved.latest) + + +__all__ = ["BASIS_MISMATCH", "BASIS_MISSING", "CODE_TEXT", "COMPILER_KEYS", "COMPILER_MISMATCH", "COMPILER_MISSING", + "FORMAT", "IDENTITIES", "INPUTS_MISSING", "KIND", + "LEGACY", "MANIFEST_FOREIGN", "MANIFEST_MISSING", "MANIFEST_TAMPERED", "PROOF_PURPOSES", "PROVEN", + "PURPOSES", "PURPOSE_COMPOSE", "PURPOSE_EXPLORE", "PURPOSE_FORMAL", "PURPOSE_ISSUE", "PURPOSE_TRIAL", + "RECORD_MISSING", "RECORD_NOT_MATCHED", "RECORD_STALE", "REVIEW_MISSING", "REVIEW_PARTIAL", + "REVIEW_REJECTED", "REVIEW_STALE", "REVIEW_UNVERIFIED", "UNPROVEN", "CardBasis", "Chained", "Judged", + "PublicationUnreadable", "Resolved", "authenticated", "basis_for", "basis_problems", "basis_rows", + "build_content", + "card_basis", "cards_summary", "chained_nodes", "chained_problems", "compiler_problems", + "compiler_versions", "content_hash", "events", "fetch_dependencies", + "highest", "judge", "latest", "manifest_problem", "observe", "parameters_of", "problem_key", + "publish", "read", + "rebuild", "recommended", "requires_proof_for", "resolve", "saved_basis", "source_cards", "upgrade_of", + "upstream_pins", "verified_content"] diff --git a/backend/app/apps/resolve.py b/backend/app/apps/resolve.py index 72f3305b..7f096b02 100644 --- a/backend/app/apps/resolve.py +++ b/backend/app/apps/resolve.py @@ -1354,7 +1354,16 @@ async def pin_upgrade(session: AsyncSession, app_id: str, version: AppVersion, def _query_artifact(source: Source, node_id: str, exec_no: Any = None) -> str | None: - """这个节点在封存范围内交回的查询快照:默认最后一次,exec 给了取第几次(从 1 数)。""" + """这个节点在封存范围内交回的查询快照:默认最后一次,exec 给了取第几次(从 1 数)。 + + 按**执行顺序**逐次取(sealed.query_records_of):同一份快照被执行两次时内容一样、工件 id 相同, + 按 artifact 去重会把两次并成一条,exec=2 就永远取不到第二次。 + """ + records = source.sealed.query_records_of(node_id) + if records: + if isinstance(exec_no, int) and not isinstance(exec_no, bool) and 1 <= exec_no <= len(records): + return str(records[exec_no - 1].get("artifact") or "") or None + return str(records[-1].get("artifact") or "") or None found = [a for a, info in source.sealed.queries.items() if info.get("node_id") == node_id] if not found: return None diff --git a/backend/app/apps/versions.py b/backend/app/apps/versions.py index 53edb038..0989bc0f 100644 --- a/backend/app/apps/versions.py +++ b/backend/app/apps/versions.py @@ -2,6 +2,10 @@ 以前三处各有各的判断:发起只认当前发布版(launch.py:92,F1),口径升版取 max(version) 把草稿也算进去(F3)。 工作流每保存一次就生成一个版本快照,没发布过的快照只是草稿:level 为空、也不是当前发布版。 + +K02 起,改图的几处(画布保存、口径草稿、回滚、发布单的保存版本)都走 append_version / save_graph 这一条路: +条件更新抢版本(CAS)+ 可选的客户端基准版本(expected_revision),旧写抛 StaleRevision;对已经接管的资产 +(文档起草建出来的口径卡)缺基准版本就拒。写入幂等(同一主体 + 工作流 + 目标的 request_id 只落一次)也在这里。 """ from __future__ import annotations @@ -12,7 +16,7 @@ from sqlalchemy import and_, or_, select, update from sqlalchemy.ext.asyncio import AsyncSession from sqlalchemy.orm.attributes import set_committed_value -from app.db.models import Workflow, WorkflowVersion +from app.db.models import CaliberWriteRequest, Workflow, WorkflowVersion from app.db.models_apps import App, AppVersion from app.db.models_process import ActionRecord @@ -21,31 +25,150 @@ RETIRE_CURRENT = "version_retire_current" RETIRE_UNPUBLISHED = "version_retire_unpublished" RETIRE_ALREADY = "version_retire_already" +#: 写入保护的机器码(K02):客户端拿着的基准版本已经过期;已接管的资产必须给基准版本(老页面照旧写会绕过并发保护) +STALE_REVISION = "stale_revision" +REVISION_REQUIRED = "revision_required" +#: 幂等键的机器码:同一个 request_id 配了不同的内容 +IDEMPOTENCY_CONFLICT = "idempotency_conflict" + class WorkflowChanged(ValueError): """保存期间另一处已经提交了新版本,需要重新读取后再编辑。""" -async def save_graph(session: AsyncSession, workflow: Workflow, graph: dict[str, Any], *, - note: str | None = None) -> bool: - """画布与口径草稿共用的保存:只新增快照,不改任何旧版本;由调用方提交事务。""" +class StaleRevision(WorkflowChanged): + """写入的基准版本对不上:客户端拿的那一版已经过期,或者另一处已经先提交了新版本。 + + current 是库里现在的版本号(409 的 current_version)。是 WorkflowChanged 的一种,原来按它兜底的调用方照旧兜得住。 + """ + + def __init__(self, message: str, current: int) -> None: + super().__init__(message) + self.current = current + + +def stale_revision_message(current: int, expected: int | None = None) -> str: + """基准版本过期时给用户的一句话:发生了什么、现在是什么版本、怎么办。 + + 客户端照旧保留自己的编辑(画布上是冲突横幅给两条路,草稿页上是提示后再点一次),所以这里不要求「刷新」, + 只说清「没替你重发、确认后再提交」。""" + if expected is None: + return f"工作流已经有新的修改(现在是 v{current}):你这次没有写进去,也没有替你重发,请确认后再提交" + return (f"这份内容基于 v{expected},现在已经是 v{current}:有人先改过。你刚才的修改还留着," + "没有替你重发,确认后可以基于最新的一版再提交一次") + + +async def append_version(session: AsyncSession, workflow: Workflow, graph: dict[str, Any], *, + note: str = "", expected_revision: int | None = None, digest: str | None = None, + status: str = "draft") -> int: + """在当前工作流上换一份新图并新增一版(回滚旧版、发布单按蓝图重建都走这里):和保存同一条 CAS 规矩。 + + expected_revision 是客户端拿着的基准版本(Workflow.version);给了就先核对,对不上抛 StaleRevision。写的时候按 + 读到的版本做条件更新,另一处在这中间提交了新版本(CAS 打不中)也是 StaleRevision,带着库里现在的版本号。 + 只新增快照、不动任何旧版本;由调用方提交事务。返回新的版本号。 + """ from app.core.artifact_store import graph_hash - if graph == workflow.graph: - return False previous = workflow.version + if expected_revision is not None and expected_revision != previous: + raise StaleRevision(stale_revision_message(previous, expected_revision), previous) result = await session.execute(update(Workflow).where( Workflow.id == workflow.id, Workflow.version == previous, - ).values(graph=graph, version=previous + 1, status="draft").execution_options(synchronize_session=False)) + ).values(graph=graph, version=previous + 1, status=status).execution_options(synchronize_session=False)) if result.rowcount != 1: - raise WorkflowChanged("工作流已有新的修改,请刷新后再保存") - for key, value in (("graph", graph), ("version", previous + 1), ("status", "draft")): + fresh = await session.scalar(select(Workflow.version).where(Workflow.id == workflow.id)) + raise StaleRevision(stale_revision_message(int(fresh or previous)), int(fresh or previous + 1)) + for key, value in (("graph", graph), ("version", previous + 1), ("status", status)): set_committed_value(workflow, key, value) - session.add(WorkflowVersion(workflow_id=workflow.id, version=workflow.version, graph=graph, - graph_hash=graph_hash(graph), note=note or "")) + session.add(WorkflowVersion(workflow_id=workflow.id, version=previous + 1, graph=graph, + graph_hash=digest or graph_hash(graph), note=note or "")) + return previous + 1 + + +async def save_graph(session: AsyncSession, workflow: Workflow, graph: dict[str, Any], *, + note: str | None = None, expected_revision: int | None = None) -> bool: + """画布与口径草稿共用的保存:只新增快照,不改任何旧版本;由调用方提交事务。 + + expected_revision 是客户端读到的 Workflow.version(乐观锁):不给就只靠 CAS 挡住并发写,给了就先把「是不是 + 基于最新一版改的」也一起核对——两个页面先后保存旧数组时,后一个被拒,而不是盖掉前一个。 + """ + if graph == workflow.graph: + if expected_revision is not None and expected_revision != workflow.version: + raise StaleRevision(stale_revision_message(workflow.version, expected_revision), workflow.version) + return False + await append_version(session, workflow, graph, note=note or "", expected_revision=expected_revision) return True +# -------------------------------------------------------------------------- +# 写入幂等(K02):同一主体在同一份资产上的同一个 request_id 只落一次 +# -------------------------------------------------------------------------- + +#: claim_write 的三种判定 +WRITE_NEW = "new" +WRITE_REPLAY = "replay" +WRITE_CONFLICT = "conflict" + + +@dataclass(frozen=True) +class WriteClaim: + """一次写入请求的幂等判定。new:第一次见;replay:同键同内容,按上一次做完的结果交回;conflict:同键不同内容。""" + + state: str + revision: int | None = None + + +def write_fingerprint(payload: Any) -> str: + """这次请求的内容指纹:只算要落下去的那几项(标题、指标、消掉的问题、目标卡),不算基准版本—— + 同一个 request_id 带着已经过期的基准版本重放,认得出是同一次请求,不报内容冲突。""" + from app.core.artifact_store import canonical_json, content_hash + + return content_hash(canonical_json(payload)) + + +def _write_key(*, actor: str | None, workflow_id: str, target: str | None, request_id: str) -> Any: + return select(CaliberWriteRequest).where( + CaliberWriteRequest.actor == (actor or ""), CaliberWriteRequest.workflow_id == workflow_id, + CaliberWriteRequest.card_id == (target or ""), CaliberWriteRequest.request_id == request_id) + + +async def claim_write(session: AsyncSession, *, actor: str | None, workflow_id: str, target: str | None, + request_id: str | None, payload_hash: str) -> WriteClaim: + """查这一次写入请求是不是已经做过:没给 request_id 就按每次都写(老客户端)。 + + 顺序重试用得上:上一次已经提交、这次再发的同键同内容请求在这里认出来,直接交回上一次的结果,不再写一遍。 + 幂等判定在版本检查之前:重放即使基准版本已经过期也要成功。 + + 并发下的收敛不靠这里(两次同时查都可能看到「还没有」):一条路是 CAS 只有一个能写出新版本,另一条路是 + 记请求时撞 (actor, workflow_id, card_id, request_id) 唯一键,调用方按 IntegrityError 再查一次,落到重放。 + """ + if not request_id: + return WriteClaim(WRITE_NEW) + row = (await session.execute(_write_key(actor=actor, workflow_id=workflow_id, target=target, + request_id=request_id))).scalar_one_or_none() + if row is None: + return WriteClaim(WRITE_NEW) + if row.payload_hash != payload_hash: + return WriteClaim(WRITE_CONFLICT) + revision = (row.result or {}).get("revision") if isinstance(row.result, dict) else None + return WriteClaim(WRITE_REPLAY, revision if isinstance(revision, int) else None) + + +async def remember_write(session: AsyncSession, *, actor: str | None, workflow_id: str, target: str | None, + request_id: str | None, payload_hash: str, revision: int | None) -> None: + """记下这一次写入请求(和这次改图同一个事务提交):同键不同内容的下一次来就认得出是冲突。 + + 顺序重试不用走这里(claim_write 已经按上一次的结果交回了);两路真并发时两边都可能没查到记录,最后靠 + (actor, workflow_id, card_id, request_id) 唯一键收敛——后到的那一路在这一步撞完整性错误,调用方回滚后 + 重查记录:赢的那一路写的图还在,按它的结果当重放交回。 + """ + if not request_id: + return + session.add(CaliberWriteRequest(actor=actor or "", workflow_id=workflow_id, card_id=target or "", + request_id=request_id, payload_hash=payload_hash, + result={"revision": revision})) + + class RetireRefused(Exception): """不退役。status_code / message / code 就是 HTTP 回的状态码、detail、机器码。""" @@ -56,6 +179,23 @@ class RetireRefused(Exception): self.code = code +def taken_over(workflow: Any) -> bool: + """这份资产是不是已经接管到工作流上了(K02):文档起草建出来的口径卡,以及从草稿接上一次运行建出来的 + (docattach)。 + + 两类都是「口径草稿的产物」,图上只有口径卡和取数,改它要走和草稿页同一条并发规矩。新的起草产物在 origin + 里写 kind=doc_draft;docattach 的产物(含以前建的)没有写 kind,只能按它建时打的标签认——两处都打了 + tags=["doc_draft"](app/ledger/authoring.py、app/ledger/docattach.py),别的创建路径(手建、蓝图 + blueprint、从运行提取 extracted、固化 certified)都没有这个标签,不会误伤。 + + 对它的图写入必须带基准版本(expected_revision):老页面、老客户端照旧无条件写会绕过并发保护,这里拒绝。 + """ + origin = getattr(workflow, "origin", None) + if isinstance(origin, dict) and origin.get("kind") == "doc_draft": + return True + return "doc_draft" in (getattr(workflow, "tags", None) or ()) + + def is_published(version: Any, *, current: int | None = None) -> bool: """这一版能不能被使用:level 不为空且没退役。level 为空的老数据,只认它就是 current(当前发布版)的情形。 @@ -89,7 +229,12 @@ async def published_versions(session: AsyncSession, workflow_id: str) -> list[An async def latest_published(session: AsyncSession, workflow_id: str) -> Any | None: - """最新的「已发布且未退役」的版本;没有就是 None。口径升版的判定用它(替换 governance.py 的 func.max)。""" + """**最高**的「已发布且未退役」的版本;没有就是 None。 + + **只用于升级发现**(K07):告诉人「有一版更新的」、口径升版的处置判定(engine/governance)都按它比。默认调用 + (目录、look、账本挑候选、正式运行的默认版本)读的是**推荐版**——Workflow.published_version 指的那一版,见 + app/apps/publications.recommended / resolve。重发一版旧版之后,推荐版是那个旧版,这里仍然是最高版。 + """ current = await _current(session, workflow_id) return (await session.execute( select(WorkflowVersion).where(WorkflowVersion.workflow_id == workflow_id, _published_clause(current)) diff --git a/backend/app/auth/chat_policy.py b/backend/app/auth/chat_policy.py index a4e96a35..3101dfde 100644 --- a/backend/app/auth/chat_policy.py +++ b/backend/app/auth/chat_policy.py @@ -9,8 +9,11 @@ start_run 先查来源和运行类别)。图本身再按这里收窄,理由 就多一处要单独核对遮罩的地方; - 工具(Agent 绑的、调用工具节点调的同一份白名单,engine/launch.tool_bindings 一并列出)只许数据源工具(db_query__ / db_schema__,查询结果按 MASK_RESULTS_OPTION 在工具边界遮)和只读的内置工具(计算、当前时间、JSON 取值、知识库检索、 - 记忆读取、分析)。分析工具不查库,只读本节点查过、在工具边界遮过的结果,遮罩列不当维度、度量(app/tools/analysis.py); - 分析卡读上游查询节点的快照,同一套遮罩。自定义工具、MCP、文件、网页、HTTP、代码执行、平台的写入能力(records_append + 记忆读取、分析、口径查询)。分析工具不查库,只读本节点查过、在工具边界遮过的结果,遮罩列不当维度、度量(app/tools/analysis.py); + 分析卡读上游查询节点的快照,同一套遮罩。**口径查询**(caliber_query,app/ledger/querycore.py)只读、按一份已发布口径取数: + 它按运行的类别选用途、用发起人当主体,派生的子运行照父 Run 的遮罩与只读边界走,**能碰哪些口径由 QueryCore 统一按资产授权 + 核**(apps/access.caliber_role:普通使用者要 use 及以上,没有授权当场拒)——白名单放开它不等于放开数据,无权口径在这一层拦。 + 自定义工具、MCP、文件、网页、HTTP、代码执行、平台的写入能力(records_append 这类)一律不许;模板拼出来的工具名({{ vars.tool }})发起时不知道是谁,也不许。调用工具节点放行的理由:它和 Agent 调同一个查询工具等价——同一个 ToolContext 带着遮罩、只读两个开关(engine/nodes/tools.py 的 _tool_ctx),参数由人写死反而比模型挑的更好核对; 周期看板、异常处置这些模板的取数节点就是它(个人应用和问数据同一份白名单,blueprints/personal.policy_problem); @@ -24,19 +27,30 @@ start_run 先查来源和运行类别)。图本身再按这里收窄,理由 的 collection 参数(参数名纠错改出来的、模型挑的)一律拒(tools/registry.ToolContext.fixed_scope)。 没在这里列出的节点类型、工具,以后加了也默认不许(白名单),要放开得先想清楚遮罩怎么守。 + +**谁是「普通使用者」(restricted_actor)。** 上面这些收窄只对开登录后的 user 角色成立:builder / admin / 关登录由各自的入口 +显式放行,资产授权函数(apps/access.caliber_role / usable_calibers)不管这几档。发起运行、准备一轮问数据、读一份口径清单的 +地方手上不都是 Principal(服务端任务只记着一个用户名),所以这里按 actor 判一次「是不是要按授权收窄的那一档」,判完再把 +资产授权交给 apps/access——两件事一处是「谁」,一处是「有没有把这一版口径给他」。判定与 `api/deps.restricted()` 同一条规则、 +同一个来源:**角色以 `Principal.role` 为准**(访问密钥认出来的身份封顶在使用者,不回库覆写;角色快照与身份不一致时以身份 +为准),只有手上**只有一个用户名**时才回库里认角色与停用。 """ from __future__ import annotations from typing import Any from app.analysis.contract import TOOL_NAMES +from app.ledger.querycore import CALIBER_QUERY #: 问数据运行里 user 角色能用的节点类型(engine/schema.py 的 NodeType 取值) CHAT_NODE_TYPES = frozenset({"input", "llm", "agent", "report", "output", "retrieve", "transform", "branch", "metrics", "merge", "analysis", "tool"}) -#: Agent 能绑的只读内置工具(tools/builtin/):五个分析工具也在内(contract.TOOL_NAMES,不查库) +#: Agent 能绑的只读内置工具(tools/builtin/):五个分析工具也在内(contract.TOOL_NAMES,不查库),以及口径查询 +#: (querycore.CALIBER_QUERY,只读、按资产授权收窄——见文件开头)。工具名只从登记处取常量,不在这里另写一个字符串 CHAT_BUILTIN_TOOLS = frozenset({"calculator", "current_time", "json_query", "kb_search", "memory_recall", - *TOOL_NAMES.values()}) + CALIBER_QUERY, *TOOL_NAMES.values()}) +#: 上面那几个内置工具给人看的说法(拒绝时的报错、提示词里都写它) +CHAT_BUILTIN_LABEL = "计算、当前时间、JSON 取值、知识库检索、记忆读取、分析、口径查询" #: 运行时改记忆范围、知识库的配置键(engine/nodes 的 ctx.cfg("memory_scope") / ctx.cfg("collection"),图级 defaults 同样生效) SCOPE_KEYS = ("memory_scope", "collection") SCOPE_REFUSED = "没有权限:使用者在问数据中不能指定记忆范围和知识库,使用的是管理员设好的默认值" @@ -94,8 +108,97 @@ def chat_graph_problem(graph: Any, *, where: str = "问数据") -> str | None: return f"没有权限:{who}的工具名由模板拼成,发起前无法确定是哪个工具,使用者在{where}中不能这样绑定工具" if not _tool_allowed(name): return (f"没有权限:{who}绑定了工具「{name}」。使用者在{where}中只能使用数据源查询和只读的内置工具" - "(计算、当前时间、JSON 取值、知识库检索、记忆读取、分析)") + f"({CHAT_BUILTIN_LABEL})") return None -__all__ = ["CHAT_BUILTIN_TOOLS", "CHAT_NODE_TYPES", "SCOPE_REFUSED", "chat_graph_problem", "chat_memory_scope"] +# -------------------------------------------------------------------------- +# 谁是「普通使用者」:要按资产授权收窄的那一档 +# -------------------------------------------------------------------------- + + +def _name_of(actor: Any) -> str: + """actor 是 Principal 就取它的用户名,是字符串就当用户名,别的按没有名字算。""" + if isinstance(actor, str): + return actor.strip() + return str(getattr(actor, "username", "") or "").strip() + + +def effective_actor(actor: Any = None) -> Any: + """这次是谁:调用方显式给的用它(用户名或 Principal),没给就取当前请求的身份(中间件写好的 `current_principal`)。 + + 调用方常常只拿得到一个记在运行上的名字(服务端任务、父 Run),HTTP 那边则什么也不用传——两处都要先归一成同一个 + 主体,再判「是不是普通使用者」和「资产授权有没有把这一版口径给他」,不然两处判的会是两个人。""" + if actor is not None: + return actor + from app.api.deps import current_principal + + return current_principal() + + +def actor_name(actor: Any = None) -> str | None: + """这次是谁的**名字**(记进运行的发起人、当认证主体):没给就取当前请求的身份;说不上来是 None。 + + 认不出的名字照样是一份「没有名字」的答案,不在这里当放行:`restricted_actor` 与资产授权都按普通使用者算, + 查不到主体就是没有授权(querycore 的 `_require_caliber` 当场拒)。""" + return _name_of(effective_actor(actor)) or None + + +def _is_limited(principal: Any) -> bool: + """一个**已经认出来的身份**要不要按资产授权收窄:和 `api/deps.restricted()` 同一条规则,角色只以 `Principal.role` 为准。 + + 不回库覆写它:访问密钥认出来的身份封顶在使用者(auth/keys.principal_for_key 一律 role="user"),拿它的用户名去库里查 + 会查到那个人是管理员、把这一档又抬回去——那是绕过。说不上是谁(没有名字)也算收窄(宁可少给一点)。""" + if not _name_of(principal): + return True + return principal.mode != "off" and not principal.at_least("builder") + + +async def _limited_name(session: Any, name: str) -> bool: + """手上只有用户名时(服务端任务、父 Run 记下来的名字)回库里认:角色、停用。停用、认不出这个人都按收窄算。 + + 这一条只在**没有更好的身份**时走(`restricted_actor` 里那两个身份都在时取更严的那一个)。""" + if not name: + return True + from sqlalchemy import select + + from app.db.models import User + + user = (await session.execute(select(User).where(User.username == name))).scalars().first() + if user is None or user.disabled: + return True + return str(user.role) not in ("admin", "builder") + + +async def restricted_actor(session: Any, actor: Any = None) -> bool: + """这次是不是「普通使用者」(开登录后不是 builder / admin 的那一档):是的话,口径能不能用按资产授权判 + (apps/access.caliber_role / usable_calibers),问数据的图按这一份白名单收窄。 + + - 关登录(auth_mode() == "off"):全部放行,等同管理员,这里交回 False; + - actor 是 Principal(这次请求的身份、访问密钥认出来的身份)时,**角色以它为准**(`Principal.role`),不回库覆写—— + 访问密钥封顶在使用者这一档,不能因为那个人的用户名在库里是管理员就被抬成放行;角色快照与身份不一致时以身份为准; + - actor 是用户名(服务端任务、父 Run 手上只有记在运行上的名字)时回库里认角色与停用;这种情况**另看当前请求的身份**: + 形参给的是名字、请求又是某个使用者(比如一把访问密钥)发来的,两个身份都在就取**更严**的那一个——名字在库里是管理员 + 也绕不过请求那一档; + - actor 没给就取当前请求的身份(`effective_actor`);连身份都给不出、也认不出人时按普通使用者算——**宁可少给一点**: + 资产授权那边查不到就是没有授权,执行时会当场拒(querycore_not_authorized)。 + + 这几档的放行写在**调用方**这里,不写进资产授权函数(apps/access 只回答「授权有没有把这一版口径给到这个主体」)。""" + from app.api.deps import Principal, auth_mode, current_principal + + if auth_mode() == "off": + return False + who = effective_actor(actor) + if isinstance(who, Principal): + return _is_limited(who) + if await _limited_name(session, _name_of(who)): + return True + if actor is not None: + # 形参给的是名字:当前请求的身份另算一道,取更严的那一个(见上面那条) + request = current_principal() + return bool(_name_of(request)) and _is_limited(request) + return False + + +__all__ = ["CHAT_BUILTIN_LABEL", "CHAT_BUILTIN_TOOLS", "CHAT_NODE_TYPES", "SCOPE_REFUSED", "actor_name", + "chat_graph_problem", "chat_memory_scope", "effective_actor", "restricted_actor"] diff --git a/backend/app/blueprints/publish_plan.py b/backend/app/blueprints/publish_plan.py index bc5a90db..0849fded 100644 --- a/backend/app/blueprints/publish_plan.py +++ b/backend/app/blueprints/publish_plan.py @@ -555,6 +555,9 @@ async def plan(session: AsyncSession, blueprint: Blueprint, *, level: str, princ first_run = bool(options["first_run"]) if isinstance(options.get("first_run"), bool) else not target.process options["first_run"] = first_run options["spec_hash"] = spec_digest(blueprint) + # 出单时这份工作流是第几版(K02):执行保存版本时对不上就停下重新出单,不把画布上别人刚改的图盖掉。 + # 还没有工作流(第一次发布)时为空,那时保存的是新建的那一版 + options["workflow_revision"] = target.workflow.version if target.workflow is not None else None problems = await _preflight(session, blueprint, target, level=level, principal=principal, options=options) row = PublishPlan(blueprint_id=blueprint.id, actor=principal.username, level=level, graph_hash=target.digest, options=options, steps=_steps(target, first_run=first_run), @@ -777,7 +780,12 @@ async def _do_preflight(session: AsyncSession, ctx: _Run) -> dict[str, Any]: async def _do_save_version(session: AsyncSession, ctx: _Run) -> dict[str, Any]: - """按图哈希判断:已有相同的版本就复用;没有就存一版(同画布保存:版本号加一、画布状态退回草稿)。""" + """按图哈希判断:已有相同的版本就复用;没有就存一版(同画布保存:版本号加一、画布状态退回草稿)。 + + 已有工作流的那条路和画布保存同一条 CAS 规矩(apps/versions.append_version):出单时记下的版本(workflow_revision) + 到执行时对不上,说明有人直接从画布改了同一份资产,停在这一步让人重新出单——不把别人刚改的图盖掉。 + """ + from app.apps.versions import StaleRevision, append_version from app.blueprints.trial import template_of bp = ctx.bp @@ -798,14 +806,19 @@ async def _do_save_version(session: AsyncSession, ctx: _Run) -> dict[str, Any]: session.add(workflow) await session.flush() version = 1 + session.add(WorkflowVersion(workflow_id=workflow.id, version=version, graph=target.graph, + graph_hash=target.digest, note=note)) else: - workflow.graph = target.graph - workflow.version += 1 - version = workflow.version - if workflow.status in ("published", "governed"): - workflow.status = "draft" - session.add(WorkflowVersion(workflow_id=workflow.id, version=version, graph=target.graph, - graph_hash=target.digest, note=note)) + planned = (ctx.options or {}).get("workflow_revision") + if isinstance(planned, int) and workflow.version != planned: + raise StepFailed(GRAPH_CHANGED, + f"出单之后「{target.name}」的画布又改过(出单时是 v{planned},现在是 v{workflow.version}):" + "这一份发布单要发的已经不是它看过的那张图,请重新出一份发布单") + try: + version = await append_version(session, workflow, target.graph, note=note, digest=target.digest) + except StaleRevision as e: + raise StepFailed(GRAPH_CHANGED, + f"保存这一版时「{target.name}」已经有新的修改({e}):请重新出一份发布单") from e bp.workflow_id = workflow.id await session.commit() await session.refresh(workflow) @@ -832,7 +845,13 @@ async def _do_publish_workflow(session: AsyncSession, ctx: _Run) -> dict[str, An if ctx.level == "governed" and not ctx.principal.at_least("admin"): raise StepFailed(ADMIN_REQUIRED, "以受管级别发布需要管理员") if is_published(snapshot, current=workflow.published_version) and snapshot.level == ctx.level: - return {"workflow_id": workflow.id, "version": snapshot.version, "level": ctx.level, "already": True} + # 已经是这一档的发布版:不再多发一次事件(发布依据是那一次留下的),照实把那一份清单交回 + from app.apps import publications + + row = await publications.latest(session, workflow.id, int(snapshot.version)) + return {"workflow_id": workflow.id, "version": snapshot.version, "level": ctx.level, "already": True, + "manifest": getattr(row, "manifest", None), + "publication_id": getattr(row, "id", None)} if not ctx.principal.at_least("admin") and await downgrades_governed(session, workflow, ctx.level): raise StepFailed(DOWNGRADE_ADMIN, f"「{workflow.name}」现在是受管级别,降为已发布需要管理员") issues = await gate_issues(session, snapshot.graph, ctx.level) @@ -840,7 +859,11 @@ async def _do_publish_workflow(session: AsyncSession, ctx: _Run) -> dict[str, An problems = [_with_who({**i, "source": "workflow"}) for i in issues or []] raise StepFailed(WORKFLOW_PUBLISH, "工作流没有通过发布检查,还没有发布", problems) out = await commit_publish(session, workflow, snapshot, ctx.level, ctx.actor) - return {"workflow_id": workflow.id, "version": out["version"], "level": out["level"]} + # K07:这一次发布实际留下的发布依据(清单、依据齐不齐、缺哪一块)记进这一步,发布单执行完能对上是哪一份 + return {"workflow_id": workflow.id, "version": out["version"], "level": out["level"], + "manifest": out.get("manifest"), "publication_id": (out.get("publication") or {}).get("id"), + "proven": (out.get("publication") or {}).get("proven"), + "problems": (out.get("publication") or {}).get("problems") or []} async def _do_create_schedule(session: AsyncSession, ctx: _Run) -> dict[str, Any]: diff --git a/backend/app/capabilities/registry.py b/backend/app/capabilities/registry.py index 7b7068f1..16788b21 100644 --- a/backend/app/capabilities/registry.py +++ b/backend/app/capabilities/registry.py @@ -304,19 +304,50 @@ async def capability_versions_for(session: AsyncSession, tool_names: list[str]) def is_platform_query(name: str) -> bool: """这个工具的结果能不能当查询快照作证(替换 nodes/tools.py、nodes/llm.py 里按名字前缀的判断,F11)。 - 认的是「平台执行」这个身份:数据源查询工具,和登记里声明了 tabular、绑定端点、由平台执行的读取。不看结果长什么样。""" + 认的是「平台执行」这个身份:数据源查询工具、K10 的口径查询工具(`caliber_query`,由 QueryCore 自己执行取数), + 和登记里声明了 tabular、绑定端点、由平台执行的读取。不看结果长什么样。""" + from app.ledger.querycore import CALIBER_QUERY from app.tools.datasource import QUERY_PREFIX - return name.startswith(QUERY_PREFIX) or name in _platform_queries + return name.startswith(QUERY_PREFIX) or name == CALIBER_QUERY or name in _platform_queries + + +def query_items(payload: Any, name: str) -> list[dict[str, Any]]: + """这次工具调用交回的结果里的查询条目——**按身份摊成一份列表**:`caliber_query` 是 queries 数组(多条), + 别的平台执行的查询(数据源查询、登记里声明了表格的端点读取)是一条。 + + 两个形状在这里合成同一种条目(工件、来源、列、行数、截断,加上 query_id / execution_id / attempt 与执行材料): + 调用方逐条过 snapshot_owned 再记台账,不会因为结果里带的是数组就只认第一条、也不会把数组误当一条。 + **是不是平台执行的查询由调用方按 is_platform_query 先认**,这里只按名字决定结果的形状。""" + from app.ledger.querycore import CALIBER_QUERY, query_entries + + if name == CALIBER_QUERY: + return query_entries(payload) + from app.engine.evidence import query_entry_fields + + found = query_entry_fields(payload) + return [found] if found else [] async def snapshot_owned(artifact_id: str, run_id: str, name: str) -> bool: - """端点读取交回的快照是不是这次运行落下的 endpoint_snapshot(防伪的第二道:名字对了,工件也得对)。数据源查询工具的 - 快照由数据层自己落,照旧不查。""" + """工具交回的快照是不是这次运行的、可以作证的那一件(防伪的第二道:名字对了,工件也得对)。 + + - 数据源查询(`db_query__`):快照由数据层自己落,照旧不查; + - `caliber_query`(K10):每条 query artifact 必须是**这次授权的父运行**自己落的,或它**明确派生的子运行**(子运行 + origin 里的 `parent_run_id` 指回父运行)落下的,且 kind 必须是 `query_snapshot`——伪造的、别的运行落的、别的种类 + 的工件一律拒(这就是父 Run 证据接入的那道门,不另建权限系统); + - 别的(登记里平台的端点读取):工件得是这次运行落下的端点快照。""" from app.tools.datasource import QUERY_PREFIX if name.startswith(QUERY_PREFIX): return True + from app.ledger.querycore import CALIBER_QUERY, PARENT_RUN_KEY + + if name == CALIBER_QUERY: + from app.data.catalog import QUERY_SNAPSHOT_KIND + + return await _query_snapshot_of_parent(artifact_id, run_id, parent_key=PARENT_RUN_KEY, + kind=QUERY_SNAPSHOT_KIND) from app.capabilities.endpoints import SNAPSHOT_KIND from app.db.base import SessionLocal from app.db.models import Artifact @@ -326,6 +357,36 @@ async def snapshot_owned(artifact_id: str, run_id: str, name: str) -> bool: return row is not None and row.kind == SNAPSHOT_KIND +async def _query_snapshot_of_parent(artifact_id: str, run_id: str, *, parent_key: str, kind: str) -> bool: + """这件工件是不是父运行(或它明确派生的子运行)落下的、且种类是查询快照。 + + 同一份内容可以有多行引用(内容寻址,不同运行产出同一件);只要有一行对上就算数。""" + from sqlalchemy import select + + from app.db.base import SessionLocal + from app.db.models import Artifact, Run + + parent = str(run_id or "") + if not artifact_id: + return False + async with SessionLocal() as session: + rows = list((await session.execute( + select(Artifact.run_id, Artifact.kind).where(Artifact.id == artifact_id))).all()) + for owner, row_kind in rows: + if str(row_kind or "") != kind: + continue + owner_id = str(owner or "") + if parent and owner_id == parent: + return True + if not parent or not owner_id: + continue + child = await session.get(Run, owner_id) + origin = child.origin if child is not None and isinstance(child.origin, dict) else None + if origin and str(origin.get(parent_key) or "") == parent: + return True + return False + + async def endpoint_request(session: AsyncSession, capability: Any, args: dict[str, Any], *, environment: str, idem_key: str | None = None, on_behalf: str | None = None, run_id: str | None = None, node_id: str | None = None, diff --git a/backend/app/chat/drive.py b/backend/app/chat/drive.py index 7e1a8041..623ce036 100644 --- a/backend/app/chat/drive.py +++ b/backend/app/chat/drive.py @@ -8,10 +8,13 @@ - 生成:generate_in 给这一次生成的请求(问数据带对话、限定的数据源;评测带变体的助手模型),catalog_view 给读哪一份数据目录 (评测按变体,问数据是当前目录)。每一条操作都先交给 on_op(问数据写进这一轮的事件日志,评测不管),思考和心跳不进结局判断。 -- 结局:reply 直接回答、asked 反问、ready 只建不跑、build_failed 建图失败、retry 带着原因重来(次数照 MAX_ATTEMPTS)、run 运行。 - 每次重来前调 on_retry(问数据记一条「重来」,把换下来的运行的用量并进这一轮)。 +- 结局:reply 直接回答、asked 反问、ready 只建不跑、build_failed 建图失败、retry 带着原因重来(次数照 MAX_ATTEMPTS)、run 运行、 + done 这一轮的运行已经在生成里跑完(固定执行的 final 带 execution.run_id:不发起第二次,收下那次运行——记进这一轮、接上 + 证据、页面能重载查看;不再整轮复核,那次运行是服务端按固定口径搭的取数图,它的成果不是自由生成的答案)。每次重来前调 + on_retry(问数据记一条「重来」,把换下来的运行的用量并进这一轮)。 - 运行:prepare_graph 改图(评测按变体写进写作模型)、run_input 填入口(问数据带前几轮的问答,评测单轮)、launch_args 给来源、 - 选项、发起人(遮罩、只读、目录视图照各自现有的规则),发起之后调 on_launched。 + 选项、发起人(遮罩、只读、目录视图照各自现有的规则;也可以连带交回改过的 graph:普通使用者的口径查询工具是 chat/launch + 补上的),发起之后调 on_launched。 - 终态:停在审批上交给 on_interrupted——评测取消(不代批),问数据照旧等人(这是两边唯一的流程差别);被驳回的记 rejected, 失败、被停止记 run_failed。 - 复核:_review(评测一直等、复核自己出错照实记一条失败的复核;问数据最多等 25 秒,见 chat/job.py)。给了 @@ -182,11 +185,15 @@ class TurnDriver: return policy.fill_input(graph, self.question, "") async def launch_args(self, session: Any, graph: dict[str, Any]) -> dict[str, Any]: - """launch_run 的其余参数:来源、选项、发起人……可以抛 LaunchRefused(照发起被拒记)。""" + """launch_run 的其余参数:来源、选项、发起人……可以抛 LaunchRefused(照发起被拒记)。 + + 准备阶段要改图时就带一项 `graph` 回来(普通使用者的口径查询工具是 chat/launch 补上的):`_launch` 用交回的那一张 + 发起,别的调用方不带这一项,用的仍是 prepare_graph 出来的图。""" raise NotImplementedError async def on_launched(self, run: Any) -> None: - """运行发起了。""" + """运行发起了。**这一轮收下的一次已经跑完的运行**(NEXT_DONE 那一档)也走这里:问数据据此把它记进这一轮(run_id 那一列、 + run 事件、meta),页面能重载查看;评测那一档不改(基类空实现)。""" async def on_interrupted(self, run_id: str, row: Any) -> Any | None: """运行停在断点上(审批、服务重启挂起):交回接着等到的运行记录,或者记好路径、交回 None。""" @@ -238,9 +245,12 @@ class TurnDriver: graph = self.prepare_graph(graph) try: async with SessionLocal() as session: + # 准备阶段的其余参数:launch_args 可能连图一起改(普通使用者的口径查询工具是服务端在 chat/launch 里补上的, + # 见那一段说明)——它交回 graph 这一项就用它,别的调用方照旧用 prepare_graph 出来的那一张 + args = await self.launch_args(session, graph) + graph = args.pop("graph", graph) inputs = payload if payload is not None else await self.run_input(session, graph) - run = await launch_run(session, graph=graph, input_payload=inputs, - **(await self.launch_args(session, graph))) + run = await launch_run(session, graph=graph, input_payload=inputs, **args) except LaunchRefused as e: self.launch_refused = e self.turn.path, self.turn.reason = "run_failed", f"运行没有发起:{e.message}" @@ -322,6 +332,8 @@ class TurnDriver: instruction = instruction or self.question # 不建图、直接运行这张图(graph),或者不发起、接着等这次运行(run_id):只有第一圈这样,重来还是照常建图 direct, follow = graph, run_id + #: 这一轮的运行是在**生成这一轮里**就跑完的那一次(固定执行):跟它一次,收下它,不再整轮复核(见模块说明) + fixed = False try: while True: if direct is None and follow is None: @@ -384,6 +396,15 @@ class TurnDriver: if step == policy.NEXT_READY: t.path, t.reason = "ready", "助手只建了图、没有运行(它判断用户要的是流程本身)" return t + if step == policy.NEXT_DONE: + # 这一轮的运行已经在生成里跑完了(固定执行):不发起第二次,收下它(下面那一圈走 follow 那一支: + # 记进这一轮、等它收尾、接上证据),也不再整轮复核 + running = str((terminal.get("execution") or {}).get("run_id") or "") + if not running: + t.path, t.reason = "build_failed", "这一轮的固定执行没有交出运行" + return t + fixed, follow = True, running + continue direct = built await self._phase("run") @@ -391,6 +412,11 @@ class TurnDriver: t.runs.append(follow) t.run_id = t.current_run = follow row = await self._follow(follow) + if row is not None and fixed: + # 收下这一次已经跑完的运行:记进这一轮(run_id 那一列、run 事件、meta),页面据此重载查看 + await self.on_launched(row) + t.path = "ran" + return t else: row = await self._run(direct) direct = follow = None diff --git a/backend/app/chat/job.py b/backend/app/chat/job.py index d45e7365..9a6c65b0 100644 --- a/backend/app/chat/job.py +++ b/backend/app/chat/job.py @@ -153,8 +153,8 @@ class ChatDriver(TurnDriver): from app.api.copilot import GenerateIn return GenerateIn(instruction=instruction, base_graph=base_graph, intent="answer", - conversation_id=self.execution.conversation_id, datasource_ids=self.datasource_ids or None, - question=self.question) + conversation_id=self.execution.conversation_id, turn_id=self.execution.turn_id, + datasource_ids=self.datasource_ids or None, question=self.question) async def on_op(self, op: dict[str, Any]) -> None: kind = op.get("op") @@ -220,7 +220,10 @@ class ChatDriver(TurnDriver): "turn_id": self.execution.turn_id}} if restricted(): try: - args["memory_scope"], args["options"] = user_chat_run(graph, self.execution.actor) + # 第三项是这次要发起的图:使用者的口径查询工具由 chat/launch 补上(有授权的口径那一份), + # drive._launch 认 args 里的 graph,发起用的是补过的那一张(见 chat/launch 模块说明) + args["memory_scope"], args["options"], args["graph"] = await user_chat_run( + session, graph, self.execution.actor) except ChatRunRefused as e: raise LaunchRefused(403, str(e)) from e return args @@ -807,7 +810,13 @@ async def _settled(driver: ChatDriver, execution: ChatTurnExecution output = run.output if isinstance(run.output, dict) else {} review = driver.last_review if driver.late_review is None else None rewritten = (review or {}).get("answer") if (review or {}).get("verdict") != "ok" else None - fields.update(status="done", answer=rewritten or record.answer_text(output), review=review or {}) + answer = rewritten or record.answer_text(output) + if (term.get("execution") or {}).get("run_id") and term.get("explanation"): + # 这一轮的运行是**生成这一轮里就跑完的固定执行**(chat/turn.NEXT_DONE):运行照常归属这一轮、能重载查看(上面那一段), + # 但它的成果不是自由生成的报告(服务端按固定口径搭的那张图),答案用 final 里那句白话——使用者看到的数与说法就是 + # api/copilot 投影出来的那一份(builder 的详细依据、user 的安全白话都在里面) + answer = str(term["explanation"]) + fields.update(status="done", answer=answer, review=review or {}) meta.update(issuance=record.slim_issuance(output.get("_issuance")), evidence=True if record.has_evidence(output) else None) return fields, meta, "done", output, usage diff --git a/backend/app/chat/launch.py b/backend/app/chat/launch.py index dd796a82..b90f1903 100644 --- a/backend/app/chat/launch.py +++ b/backend/app/chat/launch.py @@ -3,9 +3,16 @@ 以前只有 start_run 一处(浏览器发 POST /api/runs)。一轮问数据搬到服务端之后,发起运行的是这一轮的后台任务,规则不能另抄一份—— 使用者的问数据运行只许白名单里的节点和工具、记忆固定为自己的范围、查询结果在工具边界遮、数据源一律只读,这几条一处说清。 请求体能不能带记忆范围、知识库,能不能发正式运行,这些是 HTTP 请求本身的事,仍在 start_run 里判。 + +**口径查询工具是服务端补上的(K14)。** 使用者的图里不用自己画一个「按口径取数」:准备发起时在这里替它绑——有授权的 +口径至少有一份时,把 `caliber_query`(只读、按资产授权收窄)加进这张图里各个 Agent 的 `tools`;一份也没有就原样不动, +模型不会拿到一个一调就被拒的工具。模型因此在工具清单里看得到它(chat_policy 的白名单里有它、copilot 的工具清单按白名单 +列),能自己从 look 给出的**有授权的**口径里挑一张调用(look/calibers 只列这些)。绑上不等于放开数据:真正执行时 +QueryCore 统一按资产授权核(querycore 的 `_require_caliber`,没有授权当场 403 `querycore_not_authorized`)。 """ from __future__ import annotations +import copy from typing import Any @@ -13,18 +20,65 @@ class ChatRunRefused(Exception): """这张图使用者在问数据里不能运行:str(e) 就是给人看的原因(HTTP 发起时是 403 的 detail)。""" -def user_chat_run(graph: Any, actor: str | None) -> tuple[str, dict[str, Any]]: - """开登录后 user 角色发起问数据运行:交回 (记忆范围, 运行选项)。图里有白名单之外的节点、工具抛 ChatRunRefused。 +async def user_chat_run(session: Any, graph: Any, actor: str | None) -> tuple[str, dict[str, Any], dict[str, Any]]: + """开登录后 user 角色发起问数据运行:交回 (记忆范围, 运行选项, 这次要运行的图)。图里有白名单之外的节点、工具抛 ChatRunRefused。 记忆固定为这位使用者自己的范围、知识库取设置里的默认值(记忆、知识库的内容不经遮罩,见 auth/chat_policy 开头);查询结果 在工具边界就遮(事件、回答里只有遮过的值——它读得到自己这次运行的事件,api/deps.py 的 _run_scope);数据源查询一律只读, - 写语句不交给审批。""" - from app.auth.chat_policy import chat_graph_problem, chat_memory_scope + 写语句不交给审批。交回的图是 `bind_caliber_tool` 补过口径查询工具的那一份(调用方拿它发起,见模块说明)。`session` 只用来 + 读这个人有授权的口径(apps/access.usable_calibers),发起本身仍由调用方负责。""" + from app.auth.chat_policy import actor_name, chat_graph_problem, chat_memory_scope from app.tools.datasource import MASK_RESULTS_OPTION, READ_ONLY_OPTION if problem := chat_graph_problem(graph): raise ChatRunRefused(problem) - return chat_memory_scope(actor), {MASK_RESULTS_OPTION: True, READ_ONLY_OPTION: True} + # 主体归一成名字:记进记忆范围、判「是不是普通使用者」都按同一个名字算(调用方给的可能是 Principal) + name = actor_name(actor) + bound = await bind_caliber_tool(session, graph, name) + return chat_memory_scope(name), {MASK_RESULTS_OPTION: True, READ_ONLY_OPTION: True}, bound -__all__ = ["ChatRunRefused", "user_chat_run"] +async def bind_caliber_tool(session: Any, graph: Any, actor: str | None) -> dict[str, Any]: + """普通使用者的图里补上口径查询工具,交回这次要运行的图(搭建者及以上、没有可用口径、图不成形都原样交回)。 + + - 只补 **Agent 节点的 tools**:调用工具节点一次只调它写死的那个工具,补不进去(要按口径取数就把 tool 写成 caliber_query); + - 只在**这份授权确实有口径可用**时补(apps/access.usable_calibers):一份也没有就原样交回,免得模型拿到一个一调就被拒 + 的工具;builder / admin / 关登录不补(auth/chat_policy.restricted_actor)——它们本来就能自己在画布上绑; + - 改的是**副本**(deepcopy):调用方的请求体、这一轮的图都不动。""" + from app.auth.chat_policy import restricted_actor + from app.engine.launch import node_setting + from app.engine.schema import GraphSpec + from app.ledger.querycore import CALIBER_QUERY + + if not isinstance(graph, dict) or not graph.get("nodes"): + return graph + try: + spec = GraphSpec.model_validate(graph) + except ValueError: + return graph # 图不成形:交给 launch_run 照常报校验问题 + if not any(str(node.type) == "agent" for node in spec.nodes): + return graph + if not await restricted_actor(session, actor): + return graph + from app.apps.access import usable_calibers + + if not await usable_calibers(session, actor): + return graph + nodes = copy.deepcopy(graph["nodes"]) + for node in nodes: + if not isinstance(node, dict) or str(node.get("type")) != "agent": + continue + here = node.get("data") + if not isinstance(here, dict): + continue + config = here.setdefault("config", {}) + if not isinstance(config, dict): + continue + tools = [str(t) for t in (node_setting(spec, spec.node_map()[str(node.get("id"))], "tools") or [])] + if CALIBER_QUERY in tools: + continue + config["tools"] = [*tools, CALIBER_QUERY] + return {**graph, "nodes": nodes} + + +__all__ = ["ChatRunRefused", "bind_caliber_tool", "user_chat_run"] diff --git a/backend/app/chat/turn.py b/backend/app/chat/turn.py index 1161821d..38021f0d 100644 --- a/backend/app/chat/turn.py +++ b/backend/app/chat/turn.py @@ -10,7 +10,7 @@ - retry_after_review:复核之后要不要带着原图重来一次; - retry_instruction:重来时交给助手的那句话(两种措辞)。 -接口把决定交给问数据页:/copilot/generate-stream 的 final 带 next(run | ready | fail),error 带 next(retry | fail), +接口把决定交给问数据页:/copilot/generate-stream 的 final 带 next(run | ready | done | fail),error 带 next(retry | fail), /copilot/review 的结果带 retry_instruction(要重来时是那句话,不重来是 null)。问数据页照后端给的走;老后端没有这两个字段时退回它自己那份同样的 规则(tests/test_chat_turn_policy.py 逐条对照两边的常量和措辞)。评测(第 3 波)用同一组函数把一轮串起来。 @@ -26,9 +26,9 @@ from typing import Any #: 一轮最多自动试几次(含第一次):第二次还不行多半是问题本身没说清,该让用户介入(同 chat.ts 的 MAX_ATTEMPTS) MAX_ATTEMPTS = 2 -#: final 之后的三种走法(final.next):运行、只建不跑(摆着等用户点运行)、判失败(没过检查的图不拿去跑) -NEXT_RUN, NEXT_READY, NEXT_FAIL = "run", "ready", "fail" -NEXT_STEPS = (NEXT_RUN, NEXT_READY, NEXT_FAIL) +#: final 之后的四种走法(final.next):运行、只建不跑(摆着等用户点运行)、这一轮已经有了跑完的运行(固定执行)、判失败 +NEXT_RUN, NEXT_READY, NEXT_DONE, NEXT_FAIL = "run", "ready", "done", "fail" +NEXT_STEPS = (NEXT_RUN, NEXT_READY, NEXT_DONE, NEXT_FAIL) #: 别的结局:直接回答了(reply)、助手反问了等用户答(asked)、重来一次(retry:没自查过的老服务端交来没过检查的图,或者 #: 生成过程一个操作都没给) NEXT_REPLY, NEXT_ASKED, NEXT_RETRY = "reply", "asked", "retry" @@ -77,9 +77,11 @@ def next_step(terminal: Mapping[str, Any] | None, *, self_checked: bool = True) - reply:直接回答,这一轮到此为止;只有反问:等用户回答; - error:生成过程一个操作都没给(code 是 EMPTY_GENERATION)时重来一次(retry,次数由调用方按 MAX_ATTEMPTS 管,原因 取 error_reason),别的判失败; - - final:有 error 级问题时,服务端已经自查过(收到过 check 的结论)就判失败——没过的问题已经交回模型在同一轮里改过 - 了,再整轮重来是再烧一次完整生成、改的还是同一批问题;没自查过(老服务端)才重来一次(retry);模型说不运行 - (autorun=false:用户要的是流程本身、或者问了用户)只建不跑;其余运行。 + - final:这一轮的运行**已经在生成这一轮里跑完了**(固定执行的 final 带 execution.run_id,app/ledger/nlchange 的两条 + 接缝)就是 NEXT_DONE——不发起第二次,收下那次运行(chat/drive.TurnDriver 把 run_id 记进这一轮);有 error 级问题时, + 服务端已经自查过(收到过 check 的结论)就判失败——没过的问题已经交回模型在同一轮里改过了,再整轮重来是再烧一次完整 + 生成、改的还是同一批问题;没自查过(老服务端)才重来一次(retry);模型说不运行(autorun=false:用户要的是流程本身、 + 或者问了用户)只建不跑;其余运行。 """ if terminal is None: return NEXT_ASKED @@ -90,6 +92,9 @@ def next_step(terminal: Mapping[str, Any] | None, *, self_checked: bool = True) return NEXT_RETRY if terminal.get("code") in RETRY_ERRORS else NEXT_FAIL if kind != "final": return NEXT_FAIL + # 这一轮的运行已经跑完了:运行已经发生,不能再按 ready / run 解释一遍(见 _completed_run) + if _completed_run(terminal): + return NEXT_DONE if _blockers(terminal): return NEXT_FAIL if self_checked else NEXT_RETRY if terminal.get("autorun") is False: @@ -97,6 +102,14 @@ def next_step(terminal: Mapping[str, Any] | None, *, self_checked: bool = True) return NEXT_RUN +def _completed_run(terminal: Mapping[str, Any]) -> str | None: + """生成这一轮里就跑完的那次运行(final.execution.run_id);不是固定执行那一档、没有运行 id 时为 None。""" + execution = terminal.get("execution") + if not isinstance(execution, Mapping): + return None + return str(execution.get("run_id") or "") or None + + def error_reason(error: Mapping[str, Any]) -> str: """生成过程交出 error 时重来的原因(交给助手的那句话里用):error 带的 reason,没有就是 message 去掉「助手本轮未完成:」。""" reason = str(error.get("reason") or "").strip() @@ -179,7 +192,7 @@ def has_nodes(graph: Any) -> bool: return isinstance(graph, Mapping) and bool(graph.get("nodes")) -__all__ = ["EMPTY_FALLBACK", "EMPTY_GENERATION", "MAX_ATTEMPTS", "NEXT_ASKED", "NEXT_FAIL", "NEXT_READY", +__all__ = ["EMPTY_FALLBACK", "EMPTY_GENERATION", "MAX_ATTEMPTS", "NEXT_ASKED", "NEXT_DONE", "NEXT_FAIL", "NEXT_READY", "NEXT_REPLY", "NEXT_RETRY", "NEXT_RUN", "NEXT_STEPS", "QUESTION_FIELD", "RETRY_EMPTY", "RETRY_ERRORS", "RETRY_FROM_SCRATCH", "RETRY_USER_WITH_BASE", "RETRY_WITH_BASE", "blocked_reason", "empty_retry_instruction", "error_reason", "fill_input", "has_nodes", "next_step", "retry_after_review", diff --git a/backend/app/data/caliber_identity.py b/backend/app/data/caliber_identity.py index c1dd8009..52608193 100644 --- a/backend/app/data/caliber_identity.py +++ b/backend/app/data/caliber_identity.py @@ -25,10 +25,11 @@ from __future__ import annotations from collections.abc import Iterable from typing import Any -#: 指标的语义字段:只有这几样算定义,运行时值(value、rendered、inputs……)不参与哈希 +#: 指标的语义字段:只有这几样算定义,运行时值(value、rendered、inputs……)不参与哈希。 +#: time_role / refund_rule 是 K04 的业务定义字段(统计时间口径、退款处理):改了定义身份就变,绑定同步状态跟着重判。 SEMANTIC_FIELDS = ("id", "name", "expression", "unit", "decimals", "format", "kind", "definition", "params", "external", "rule", "assessment", "grain", "time_field", "numerator", "denominator", "dimensions", "filters", - "contract") + "contract", "time_role", "refund_rule") def _blank(value: Any) -> bool: diff --git a/backend/app/db/base.py b/backend/app/db/base.py index 551b6d51..fee6da95 100644 --- a/backend/app/db/base.py +++ b/backend/app/db/base.py @@ -487,6 +487,12 @@ _COLUMN_MIGRATIONS: list[tuple[str, str, str]] = [ # 工作进程登记的代码版本、库结构版本(app/cluster/version.py:不许新旧版本混跑) ("cluster_workers", "code_version", "VARCHAR(200)"), ("cluster_workers", "schema_version", "VARCHAR(64)"), + # 发布依据(K07):发布这一刻这份资产要不要证明。存量事件行回填 0(模型是 NOT NULL,所以迁移里带 DEFAULT); + # 判定改成「事件行这么说,或现在仍接管着」,回填 0 不会放松——存量事件照旧看当前的接管状态 + ("workflow_publications", "required", "BOOLEAN DEFAULT 0"), + # 增量重导入的持久对齐键(K11):存量工作项回填空串——空串不参与按对齐键的匹配, + # 不会被误当成「同一项」串上旧决定(宁可不匹配,也不按位置猜) + ("caliber_import_items", "align_key", "VARCHAR(64) DEFAULT ''"), ] #: 迁移补上的列要建的索引:(索引名, 表, 列或多列)。create_all 不碰已有的表,表上新列的索引也就不会建。 @@ -503,6 +509,8 @@ _INDEX_MIGRATIONS: list[tuple[str, str, str | tuple[str, ...]]] = [ ("ix_conversations_created_by", "conversations", "created_by"), # 口径账本按种类反查工件(kind=caliber_match,next-round 02 做法 2) ("ix_artifacts_kind", "artifacts", "kind"), + # 增量重导入的工作项按持久对齐键认(K11):候选顺序、条数变了也要认得出同一个工作项 + ("ix_caliber_import_items_align_key", "caliber_import_items", "align_key"), ] diff --git a/backend/app/db/models.py b/backend/app/db/models.py index a2d9793f..67ae8dee 100644 --- a/backend/app/db/models.py +++ b/backend/app/db/models.py @@ -1139,6 +1139,272 @@ class CaliberDraft(Base, TimestampMixin): model_id: Mapped[str | None] = mapped_column(String(120), default=None) +class CaliberWriteRequest(Base, TimestampMixin): + """对一份已接管的口径资产的写入请求(K02 幂等):按(主体 + 工作流 + 目标卡 + request_id)认这一次请求。 + + 客户端重试(网络断了、页面重发)时带着同一个 request_id 再来:内容指纹一样就按上一次做完的结果交回, + 不再新增版本;同键不同内容报冲突(409)。记在库里而不是内存里,是因为同一个请求可能在另一个进程、或者 + 服务重启之后才重试。request_id 由客户端给,不给就照旧按每次请求都写(老客户端的行为)。 + """ + + __tablename__ = "caliber_write_requests" + __table_args__ = (UniqueConstraint("actor", "workflow_id", "card_id", "request_id"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + #: 发起这次写入的主体(开登录时是认证过的用户名,关登录时是自报署名,照实记) + actor: Mapped[str] = mapped_column(String(120), default="") + workflow_id: Mapped[str] = mapped_column(ForeignKey("workflows.id", ondelete="CASCADE")) + #: 这次请求针对的那张口径卡;只改标题这类不碰图的请求记空串(列非空,唯一键才认得住) + card_id: Mapped[str] = mapped_column(String(64), default="") + request_id: Mapped[str] = mapped_column(String(64)) + #: 这次请求的内容指纹(标题、指标、消掉的问题、目标卡):同键同指纹才算重放 + payload_hash: Mapped[str] = mapped_column(String(64)) + #: 上一次做完的结果:{"revision": 版本号}。重放按它核对,不按它去改图 + result: Mapped[dict[str, Any]] = mapped_column(default=dict) + + +class CaliberValidationRecord(Base, TimestampMixin): + """一次试跑留下的一条验证记录(K05,**只追加**)。 + + 试跑成功、绑定对齐、业务确认和正式可用是四件不同的事:这张表只记「这次试跑在什么定义/绑定上、拿什么输入、 + 和什么独立期望比、结果是什么」。定义或绑定一变,旧记录还在(历史可追踪),但不再算覆盖新版本——覆盖与否 + 由 `app/ledger/validation.covers_current` 读的时候现算,不写在这里。 + + 一行 = 一次试跑的一次终态。同一份草稿的不同试跑各有一行;晚结束的旧试跑即使不能替换当前 trial 指针, + 也照旧追加自己这一行(`trial_id` + `status` 唯一,重复保存同一次终态只落一行)。 + """ + + __tablename__ = "caliber_validation_records" + __table_args__ = (UniqueConstraint("draft_id", "trial_id", "status"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + draft_id: Mapped[str] = mapped_column(ForeignKey("caliber_drafts.id", ondelete="CASCADE"), index=True) + workflow_id: Mapped[str | None] = mapped_column( + ForeignKey("workflows.id", ondelete="SET NULL"), default=None, index=True + ) + #: 这次试跑对着的图版本(Workflow.version;读的时候现算覆盖,不用它判是否有用) + version: Mapped[int] = mapped_column(Integer, default=1) + #: 这次验证绑定的那张源头口径卡 + card_id: Mapped[str] = mapped_column(String(64), default="") + #: 这次验证覆盖的指标(卡上的 metric_id,按卡的顺序) + metric_ids: Mapped[list[Any]] = mapped_column(default=list) + #: 定义依据:卡的定义指纹(data/caliber_identity.definition_hash) + definition_hash: Mapped[str] = mapped_column(String(64), default="") + #: 绑定依据:取数节点 id → 绑定指纹(app/ledger/bindings.fingerprint) + binding_fingerprints: Mapped[dict[str, Any]] = mapped_column(default=dict) + #: 取数语义指纹:含 SQL、数据源和上游依赖(data/caliber_identity.semantic_hash),排除布局 + semantic_hash: Mapped[str] = mapped_column(String(64), default="") + #: 这次跑的那张图的图指纹(工件的执行哈希;版本行被删了也能认出是哪张图) + execution_hash: Mapped[str] = mapped_column(String(64), default="") + #: 独立期望:{"source": …, "metrics": {metric_id: 值}, "note": …};没有期望时为空 + expectation: Mapped[dict[str, Any] | None] = mapped_column(default=None) + expectation_hash: Mapped[str] = mapped_column(String(64), default="") + #: 期望来自哪里:human_confirmed / fixture / independent_computation + expectation_source: Mapped[str] = mapped_column(String(40), default="") + #: 点名的那套样例(可空):固定 fixture 的编号和版本 + sample_id: Mapped[str] = mapped_column(String(120), default="") + sample_version: Mapped[str] = mapped_column(String(40), default="") + #: 规范化之后的入口输入与它的哈希(和试跑记的 inputs_hash 同一份) + inputs: Mapped[dict[str, Any]] = mapped_column(default=dict) + inputs_hash: Mapped[str] = mapped_column(String(64), default="") + #: 验证方法版本(app/ledger/validation.METHOD_VERSION):比较口径本身的版本 + method_version: Mapped[int] = mapped_column(Integer, default=1) + #: 实际结果:metric_id → {value, status, rendered, rows, masked, shape, findings} + actual: Mapped[dict[str, Any]] = mapped_column(default=dict) + #: 状态:matched / mismatched / observed / unverified / failed + status: Mapped[str] = mapped_column(String(20), default="observed", index=True) + #: 逐条问题(给人看,也是机器判别的依据) + problems: Mapped[list[Any]] = mapped_column(default=list) + #: 这一次试跑的标识与运行引用 + trial_id: Mapped[str] = mapped_column(String(64), default="") + run_id: Mapped[str] = mapped_column(String(64), default="") + #: 发起这次试跑的主体(开登录时是认证用户名) + actor: Mapped[str | None] = mapped_column(String(120), default=None) + #: 这一行是怎么来的:trial(保存试跑时追加)/ late(读的时候补记晚完成的试跑) + origin: Mapped[str] = mapped_column(String(20), default="trial") + + +class CaliberReviewDecision(Base, TimestampMixin): + """对一条验证记录的审阅决定(K05,**只追加**):确认或驳回,绑定认证主体、确认范围和所审记录的依据。 + + **审批人只能来自服务端身份**(接口不收 actor 字段)。**模型不能写审批人,也不能写批准状态**:这里没有 + 任何一条路径是从模型回复或请求体里取「谁批了」「批过了」的。 + + 决定绑的是**所审记录的定义/绑定依据**(definition_hash / binding_fingerprints / semantic_hash 记在 basis 里), + 不是「这张卡现在长什么样」:定义或绑定一改,旧决定保留但不再覆盖新版本(读的时候现算 covers_current)。 + 同一份记录可以被多次审阅(追加),显示用最新的一条;驳回也是追加一条,不改写旧的。 + """ + + __tablename__ = "caliber_review_decisions" + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + draft_id: Mapped[str] = mapped_column(ForeignKey("caliber_drafts.id", ondelete="CASCADE"), index=True) + #: 审的是哪一条验证记录(caliber_validation_records.id) + record_id: Mapped[str] = mapped_column( + ForeignKey("caliber_validation_records.id", ondelete="CASCADE"), index=True + ) + workflow_id: Mapped[str | None] = mapped_column( + ForeignKey("workflows.id", ondelete="SET NULL"), default=None, index=True + ) + #: confirmed / rejected + decision: Mapped[str] = mapped_column(String(20), default="confirmed") + #: 认证主体(服务端身份,不从请求体取) + actor: Mapped[str | None] = mapped_column(String(120), default=None) + #: 这个主体是认证过的还是自报署名(关登录时) + verified: Mapped[bool] = mapped_column(default=False) + #: 确认范围:这份记录覆盖的指标(可以只确认其中一个子集) + scope: Mapped[list[Any]] = mapped_column(default=list) + #: 所审记录的依据版本:{version, definition_hash, binding_fingerprints, semantic_hash, method_version} + basis: Mapped[dict[str, Any]] = mapped_column(default=dict) + note: Mapped[str | None] = mapped_column(Text, default=None) + + +class WorkflowPublication(Base, TimestampMixin): + """一次发布留下的发布事件(K07,**只追加**):这一版按什么依据发布过。 + + 发布时按那一版不可变的图算出一份**确定**的清单,存成内容寻址工件(`manifest` 就是它的内容哈希、也就是工件 id), + 再在这里追一行。清单固定图指纹、每张源头口径卡的定义/绑定/取数语义指纹、参数契约、当前的取数依赖、编译器与验证 + 方法版本,以及发布这一刻引用的验证记录与审阅决定。 + + **重发旧版产生新事件,旧事件和旧清单一个字不改**;`workflow_versions` 上那几列发布元数据(级别、发布人、发布时间、 + 目录/结构/能力版本)是**最新投影**,记的是最近一次发布的结果。发布指针 `Workflow.published_version` 是**推荐指针**, + 问的是「默认调用读哪一版」,和最新一次发布事件一致;最高已发布版另算(`apps/versions.latest_published`,只用于升级 + 发现)。 + + **观察到的环境不进清单内容**(发布人、时间、目录/结构/能力版本、绑定工具当前在不在):清单要能被重建,所以内容只由 + 原始输入(这一版不可变的图 + 引用的那两行记录)决定;这些观察记在 `observed` 上,单独标出来。加这一列之前发布的 + 版本没有这一行,读的时候按「老资产」处理(formal_legacy),不 backfill、不伪造历史。 + """ + + __tablename__ = "workflow_publications" + __table_args__ = (Index("ix_workflow_publications_workflow_version", "workflow_id", "version"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + workflow_id: Mapped[str] = mapped_column(ForeignKey("workflows.id", ondelete="CASCADE")) + #: 发布的是哪一版(workflow_versions.version) + version: Mapped[int] = mapped_column(Integer) + #: 这一版按哪一档发布的:published | governed + level: Mapped[str] = mapped_column(String(20), default="published") + #: 这一版图的指纹(和 WorkflowVersion.graph_hash 同一份):清单读出来和版本行对不上时认这个 + graph_hash: Mapped[str] = mapped_column(String(64), default="") + #: 清单工件 id(内容寻址,= 清单内容的哈希,也是格式里的 agentlab.publication/1) + manifest: Mapped[str] = mapped_column(String(64), default="", index=True) + format: Mapped[str] = mapped_column(String(40), default="") + #: 这一版每张源头口径卡的依据摘要(和清单内容里的那一份逐字相同):不读工件也能看「依据齐不齐」 + cards: Mapped[list[Any]] = mapped_column(default=list) + #: 发布这一刻依据是否完整(每张卡都有 matched 且认证确认覆盖全部指标的记录):之后补的验证/审阅不会回头改这一行 + proven: Mapped[bool] = mapped_column(default=False) + #: 发布这一刻这份资产要不要证明(publish 按当时的接管状态判,记下来):**判定按这一行或当前接管状态,两者取或**—— + #: 发布时要求过证明的,后来把接管标记去掉(清 tags 之类)也不能把这一版降级成「不需要证明」。加这一列之前的事件行 + #: 回填 0,判定照旧看当前的接管状态(不 backfill 猜历史,也不会因为补了个 0 就放松) + required: Mapped[bool] = mapped_column(default=False) + #: 观察到的环境(无法从原始输入重建的那些,不进清单内容的哈希) + observed: Mapped[dict[str, Any]] = mapped_column(default=dict) + #: 发布人(服务端记,不从请求体取;关登录时是自报署名) + actor: Mapped[str | None] = mapped_column(String(120), default=None) + + +# -------------------------------------------------------------------------- +# 增量重导入与 B/L/R 三方合并(K11) +# -------------------------------------------------------------------------- + + +class CaliberImportRun(Base, TimestampMixin): + """一次增量重导入(K11):把新一段材料重新抽成候选 R,和当前图 L、字段基线 B 逐字段比对。 + + **R 的来源是可还原的。** 这次抽取读到的原文按内容寻址存成不可变工件(`source_snapshot` 记引用,同 K05 的来源快照), + `visible_chunk_ids` 记**实际进了这次提示**的段落,解析/模型/提示各留版本。工件之外还记这份引用,历史结果才知道是按 + 哪一版抽的、当时能看到哪些段落。 + + **任务进度不是字段基线 B。** `checkpoint` 只记「哪些工作项还没做完、哪些字段已经被接受」,重启后据此显式恢复未完成 + 的工作项;B 在草稿 payload 的 field_baseline 上,只随「接受字段」推进(见 app/ledger/reimport.py、fieldbaseline.py)。 + + 这张表同时是后台任务的载体(core/job_runtime 的生命周期,同 CaliberDraftJob):`status` 用它那一套词,`owner` 是认领 + 这一行的进程,重启时属主不在了的记 interrupted、不自动续跑(界面点「恢复」接着做)。 + """ + + __tablename__ = "caliber_import_runs" + #: 同一份草稿 + 同一个客户端 request_id 只建一次(request_id 为 NULL 的不参与去重:SQLite / PostgreSQL 的唯一索引都不把 + #: 多个 NULL 当成重复)。两路真并发同时建时靠这条收敛,接口按完整性错误重查一次交回赢的那一次。 + __table_args__ = (UniqueConstraint("draft_id", "request_id"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + draft_id: Mapped[str] = mapped_column( + ForeignKey("caliber_drafts.id", ondelete="CASCADE"), index=True + ) + #: L 所在的工作流(草稿接管到工作流上之后才有);工作流删了这次导入照旧在,只丢这条线索 + workflow_id: Mapped[str | None] = mapped_column( + ForeignKey("workflows.id", ondelete="SET NULL"), default=None, index=True + ) + #: queued | running | ready | partial | failed | cancelled | interrupted(core/job_runtime 的状态词) + status: Mapped[str] = mapped_column(String(20), default="queued", index=True) + #: R 的来源快照引用(不可变工件):{artifact_id, kind, version, content_hash, documents, chunk_ids} + source_snapshot: Mapped[dict[str, Any]] = mapped_column(default=dict) + #: 实际进了这次提示的段落(被截断丢掉的段落不在里面:引用它核不上,也不许当引用) + visible_chunk_ids: Mapped[list[Any]] = mapped_column(default=list) + #: 这次抽取用的提示词 / 解析 / 模型版本 + prompt_version: Mapped[int] = mapped_column(Integer, default=0) + parse_version: Mapped[int] = mapped_column(Integer, default=0) + model_id: Mapped[str | None] = mapped_column(String(120), default=None) + #: 客户端给的幂等键:同一份草稿 + 同一个 request_id 只建一次 run(空的不参与去重) + request_id: Mapped[str | None] = mapped_column(String(64), default=None) + #: 这次导入是服务端从认证主体上取的(不从请求体取);关登录时是自报署名 + actor: Mapped[str | None] = mapped_column(String(120), default=None) + #: 任务恢复用:{accepted: [...], done: [...], material_hash: …}。**不是字段基线 B** + checkpoint: Mapped[dict[str, Any]] = mapped_column(default=dict) + error: Mapped[str | None] = mapped_column(Text, default=None) + #: 认领这一行的进程(core/job_runtime 的多进程接手靠它) + owner: Mapped[str | None] = mapped_column(String(120), default=current_owner) + started_at: Mapped[datetime | None] = mapped_column(UTCDateTime(), default=None) + finished_at: Mapped[datetime | None] = mapped_column(UTCDateTime(), default=None) + #: 读列表用的计数投影(每次都从工作项现算,这里只是缓存一份方便排序显示) + items_total: Mapped[int] = mapped_column(Integer, default=0) + items_decided: Mapped[int] = mapped_column(Integer, default=0) + + +class CaliberImportItem(Base, TimestampMixin): + """这次导入里的一个工作项:一条候选指标 R,逐字段记三方(B 基线 / L 当前 / R 候选)和它现在的处置。 + + **逐项状态可恢复。** 每一项自己带状态和对齐依据;抽取被中断之后,已经做完的项原样留着,恢复只处理还没做完的 + (见 reimport.resume)。`fields` 是逐字段的 {b, l, r, state, ...}:state 是 no-conflict 更新 / 人工冲突 / 新增候选 / + 缺失候选 / 不变 / 需要人工对齐(baseline_unknown)之一——机器按它判能不能接受,界面按它显示。 + + 对齐只认稳定的 metric_id 和来源证据(引用指向哪几段),**不按名称相似度自动合并**:名字像不等于同一条指标, + 同名不同范围要人来定(见 reimport.align)。 + """ + + __tablename__ = "caliber_import_items" + __table_args__ = (UniqueConstraint("run_id", "seq"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + run_id: Mapped[str] = mapped_column( + ForeignKey("caliber_import_runs.id", ondelete="CASCADE"), index=True + ) + #: 这次候选里的序号(抽取确定,恢复时按它认得同一个工作项) + seq: Mapped[int] = mapped_column(Integer, default=0) + #: 持久对齐键:稳定 metric 身份 + 规范化来源证据(段落 id)。**恢复时按它认同一个工作项**, + #: 不按候选位置 seq 搬接受 / 拒绝的决定——顺序变了、条数变了都不会串项。 + align_key: Mapped[str] = mapped_column(String(64), default="", index=True) + #: 对齐到的 L 指标 id(稳定身份,写回 L 时认它);没对齐上时是空串 + metric_id: Mapped[str] = mapped_column(String(64), default="") + #: 候选 R 自己的 id(不一定稳定,只作识别) + candidate_id: Mapped[str] = mapped_column(String(64), default="") + name: Mapped[str] = mapped_column(String(200), default="") + #: pending | update | conflict | new | manual | unchanged | partial | accepted | rejected | failed + status: Mapped[str] = mapped_column(String(20), default="pending", index=True) + #: 对齐依据:{"mode": metric_id|evidence|new|manual, "reason": …, "evidence": […], "live_evidence": […]} + align: Mapped[dict[str, Any]] = mapped_column(default=dict) + #: 逐字段三方:{path: {"b": …, "l": …, "r": …, "state": …, "r_hash": …, "decided": accepted|rejected|null}} + fields: Mapped[dict[str, Any]] = mapped_column(default=dict) + #: 已经接受的字段路径(写进 L 并推进 B 的那几格) + accepted: Mapped[list[Any]] = mapped_column(default=list) + #: 已经拒绝的字段路径(保持 L 不动的那几格) + rejected: Mapped[list[Any]] = mapped_column(default=list) + #: 上次接受时落到哪一版图(工作流的 version) + applied_revision: Mapped[int | None] = mapped_column(Integer, default=None) + error: Mapped[str | None] = mapped_column(Text, default=None) + + # -------------------------------------------------------------------------- # 应用平台(docs/design/app-platform-and-look.md §3.1):按领域分文件,这里统一导入, # 让 init_db 的 create_all 和其他模块 `from app.db.models import ...` 都认得到 diff --git a/backend/app/engine/evidence.py b/backend/app/engine/evidence.py index 77da516d..a52a3c70 100644 --- a/backend/app/engine/evidence.py +++ b/backend/app/engine/evidence.py @@ -118,6 +118,12 @@ class EvidenceEntry(TypedDict, total=False): via: str # 外层包装的工件(query_snapshot 外面的 tool_snapshot) call_id: str # agent 工具记下的那次调用(查询、分析) tool: str + #: query 专有(K10):这次执行的执行身份。query_id 是**逻辑**查询身份(同一个节点/别名执行多次都一样), + #: execution_id 是**这一次执行**的身份(唯一),attempt 是第几次尝试(和 exec 一个意思,老条目只有 exec)。 + #: 同一份快照被两次执行时内容一样、工件 id 相同,靠这三样才分得出是哪一次;老条目一个都没有,退回按 artifact 认。 + query_id: str + execution_id: str + attempt: int #: analysis 专有(app/analysis/contract.ledger_entry):算子、模式、算成没算成(ok / refused)、判定码、输入快照的 #: sha256(去重、保序);分析卡来的另记那一项的 id(item),agent 工具来的记 call_id op: str @@ -235,6 +241,29 @@ def cell_eid(artifact: str | None, row: int, column: str) -> str: return make_eid("cell", artifact, {"row": row, "column": column}) +#: 新 query 台账条目带的执行身份(K10,见 EvidenceEntry 的那几行) +QUERY_EXECUTION_KEYS = ("query_id", "execution_id", "attempt") + + +def query_identity(entry: dict[str, Any] | None) -> dict[str, Any]: + """一条查询台账条目的执行身份:新条目带 query_id / execution_id / attempt,老条目一个都没有(空 dict)。""" + if not isinstance(entry, dict): + return {} + out: dict[str, Any] = {} + for key in QUERY_EXECUTION_KEYS: + value = entry.get(key) + if value not in (None, ""): + out[key] = value + return out + + +def query_eid(kind: str, artifact: str | None, entry: dict[str, Any] | None) -> str: + """query / retrieval 条目的 eid。带了执行身份(新条目)就把它算进去:同一份快照被两次执行**各得一个 + eid**,目录里是两条点得开的记录;老条目没有执行身份,和以前一字不差地按 artifact 算(不要把所有旧 + eid 重算)。定位子(locator)还是空:这一点归条目的身份,不归工件里的某个格子。""" + return make_eid(kind, artifact, query_identity(entry)) + + # -------------------------------------------------------------------------- # 台账:节点执行器写条目时用的几件小事 # -------------------------------------------------------------------------- @@ -1028,10 +1057,13 @@ def build_catalog( else: continue catalog[alias] = { - "alias": alias, "kind": kind, "eid": make_eid(kind, entry.get("artifact"), {}), + # 同一份快照被两次执行(循环里、两个节点写同一条 SQL)时 artifact 一样:eid 把执行身份也算进去, + # Q1、Q2 各有各的 eid;旧条目没有执行身份,算出来和以前一字不差。身份也照抄进条目,消费方据此 + # 认得出这次引用的是哪一次执行(sealed.query_at、apps/resolve._query_artifact) + "alias": alias, "kind": kind, "eid": query_eid(kind, entry.get("artifact"), entry), "locator": {}, **{k: entry[k] for k in ("node_id", "exec", "artifact", "via", "call_id", "tool", "source", - "columns", "rows", "truncated") if k in entry}, + "columns", "rows", "truncated", *QUERY_EXECUTION_KEYS) if k in entry}, "label": label, } if schemas or shaped: diff --git a/backend/app/engine/evidence_reader.py b/backend/app/engine/evidence_reader.py index c28f0360..89b8e55c 100644 --- a/backend/app/engine/evidence_reader.py +++ b/backend/app/engine/evidence_reader.py @@ -30,8 +30,12 @@ class Sealed: ledger: set[tuple[str, str]] = field(default_factory=set) #: 节点 id → 它最后一次 node.finished 的产出工件 id outputs: dict[str, str] = field(default_factory=dict) - #: 封存范围内交回过的查询快照:工件 id → {node_id, tool, source, via, call_id, exec} + #: 封存范围内交回过的查询快照:工件 id → {node_id, tool, source, via, call_id, exec, query_id, …} + #: 同一份快照被两次执行时这里只留一条(工件 id 相同、内容一样),要逐次区分用 query_records queries: dict[str, dict[str, Any]] = field(default_factory=dict) + #: 封存范围内交回过的查询快照,**按事件顺序逐条**记:同一份快照被两次执行(循环里、两个节点写同一条 SQL) + #: 就是两条,各自带执行身份(K10)。每条是 {artifact, node_id, exec, query_id, execution_id, attempt, …} + query_records: list[dict[str, Any]] = field(default_factory=list) #: 口径卡节点 id → 封存范围内它的 caliber.upgrade 事件(升版处置) upgrades: dict[str, dict[str, Any]] = field(default_factory=dict) #: 封存范围内 node.finished.evidence 的台账条目,按事件顺序(给可疑实体找「最接近的名字」重建目录用) @@ -80,6 +84,39 @@ class Sealed: out += [nid for nid, kind in self.types.items() if "/" in nid and kind == node_type] return out + def query_records_of(self, node_id: Any) -> list[dict[str, Any]]: + """这个节点交回过的查询快照,按执行先后(同一次执行只有一条)。同一份快照被执行两次就两条, + 老条目、新条目都在(老条目也记 exec,只是没有 execution_id)。""" + wanted = str(node_id) + return [r for r in self.query_records if str(r.get("node_id") or "") == wanted] + + def query_at(self, artifact: Any, *, node_id: Any = None, exec_no: Any = None, + execution_id: Any = None) -> dict[str, Any] | None: + """按执行身份取那一次查询:新条目按 (artifact, node_id, exec/attempt, execution_id) 认。 + + exec=2 取第二次而不是第一次:先按 exec/attempt 对,对不上再按这个节点的第 N 条。老条目(一个执行 + 身份字段都没有)也照这条走——它们同样记了 node_id / exec,逐次记的 query_records 里分得开;只有 + 连台账条目都没有(工具只回了 tool.end)时才退回 queries 里按 artifact 的那一份,和以前一样。 + """ + key = str(artifact or "") + records = [r for r in self.query_records if str(r.get("artifact") or "") == key] + if execution_id not in (None, ""): + hit = next((r for r in records if r.get("execution_id") == execution_id + and (node_id in (None, "") or str(r.get("node_id") or "") == str(node_id))), None) + if hit is not None: + return hit + if node_id not in (None, ""): + mine = [r for r in records if str(r.get("node_id") or "") == str(node_id)] + if exec_no is not None: + hit = next((r for r in mine if r.get("exec") == exec_no or r.get("attempt") == exec_no), None) + if hit is not None: + return hit + if isinstance(exec_no, int) and not isinstance(exec_no, bool) and 1 <= exec_no <= len(mine): + return mine[exec_no - 1] + if mine: + return mine[-1] + return self.queries.get(key) + def payload_of(self, node_ids: list[str]) -> dict[str, Any] | None: """这几个节点里最后跑完的那个的产出,从封存的事件指向的工件里取。""" for node_id in reversed([nid for _, t, nid, _ in self.events if t == "node.finished" and nid in node_ids]): @@ -148,8 +185,15 @@ async def read_sealed(run_id: str) -> Sealed: artifact = str(entry["artifact"]) if entry.get("kind") == "query": out.queries[artifact] = { - "node_id": node_id, **{k: entry[k] for k in ("tool", "source", "via", "call_id", "exec") + "node_id": node_id, **{k: entry[k] for k in ("tool", "source", "via", "call_id", "exec", + "query_id", "execution_id", "attempt") if entry.get(k) is not None}} + # 逐次记一条(同一份快照两次执行就是两条):eid、出处链、app 按 exec 取快照都靠它认得出是哪一次 + out.query_records.append({ + "artifact": artifact, "node_id": node_id, + **{k: entry[k] for k in ("tool", "source", "via", "call_id", "exec", + "query_id", "execution_id", "attempt") + if entry.get(k) is not None}}) elif entry.get("kind") == "schema": out.schemas[artifact] = {"node_id": node_id, "source": entry.get("source")} elif entry.get("kind") == "retrieval": diff --git a/backend/app/engine/launch.py b/backend/app/engine/launch.py index 4ba3897e..4aba4f74 100644 --- a/backend/app/engine/launch.py +++ b/backend/app/engine/launch.py @@ -36,6 +36,8 @@ VERSION_RETIRED = "run_version_retired" VERSION_HASH_MISMATCH = "run_version_hash_mismatch" #: 发布之后这一版用到的能力的治理版本变了:只提醒、不拦(同数据目录漂移) CAPABILITY_DRIFT = "capability_drift" +#: 正式运行固定了哪一份发布依据(K07):这条日志写在发起时的事件流里,运行记录上回看得到 +PUBLICATION_CODE = "publication.pinned" #: 正式运行里子工作流节点固定的版本没有发布过、已经退役(D-q)的机器码,和发布门禁、应用检查同一套:见 apps/versions.py #: 的 SUBGRAPH_UNPUBLISHED / SUBGRAPH_RETIRED 和 subgraph_pin_problems @@ -98,6 +100,8 @@ async def launch_run( formal = run_class == "formal" # 发布时记下的能力版本(正式运行才比,见 _with_capability_snapshot) published_capabilities: dict[str, Any] | None = None + # 这次正式运行固定的发布依据(K07):哪一版、哪份清单、什么身份。写进运行来源和事件流(探索运行为 None) + publication_info: dict[str, Any] | None = None if formal: # 正式运行的全部语义就这一条规则:必须引用一个不可变的已发布版本。 @@ -163,6 +167,25 @@ async def launch_run( raise LaunchRefused(409, ";".join(errors)) # 处置声明了,固定的那一版本身还得在用(D-q):两条都拦,先说升版是沿用以前的提示顺序 await _refuse_unpublished_subgraphs(session, spec) + # 发布依据(K07):每次有发布事件的正式运行都要过这一套——先复验清单工件本身(read 复验 + 编译器约定, + # 和 K09 的固定执行同一份核对)、再核清单覆盖这一版(错图/缺卡)、逐张卡认清单里引用的记录与审阅,最后按同一 + # 用途递归判转抄卡固定引用的上游那张卡。老资产(这一版没有清单)保持原行为,只是身份记 formal_legacy; + # 不需要证明的记 formal_unproven。**这是正式身份的唯一入口**:别的入口(画布、应用、定时任务、钩子、按口径 + # 出具)都要经过这里,绕不过去。 + # explicit 按调用方有没有点名版本记:默认发起只解析一次推荐版(run_version 就在上面定下来了,之后不再读指针, + # 并发下指针漂移只影响下一次发起),运行来源里照实写「不是点名的那一版」 + from app.apps import publications as caliber_publications + + judged = await caliber_publications.judge(session, workflow, version=run_version, + purpose=caliber_publications.PURPOSE_FORMAL, snapshot=snapshot, + explicit=version is not None) + if judged is not None: + refusal = judged.refusal + if refusal is not None: + raise LaunchRefused( + 409, f"「{workflow.name}」v{run_version} 的发布依据还不够,不能作为正式运行发起:{refusal[1]}", + refusal[0]) + publication_info = judged.as_dict() # 数据目录和口径卡不同:目录是给人和助手看的说明,不是运行的输入。发布之后变了只提醒、不拦—— # 拦下来等于让一次文字修订卡住正式出具 catalog_changes = await catalog_drift(session, snapshot.catalog_versions) @@ -198,8 +221,12 @@ async def launch_run( # 按不按受管出具在发起这一刻定下来:status 反映的是当前画布,中途改图、审批停下再恢复时再去读它, # 报告节点和出口复核可能各读到不同的值 notes.append(("log", None, governance_note(governed=governed, workflow_name=name, version=run_version))) - if catalog_changes: - # 之后回看这次正式出具,能知道当时的目录和发布时不一样、差在哪几张表。每张表带 impact:direct 写死的 + if publication_info is not None: + # K07:这次正式运行固定的是哪一份发布依据、什么身份(formal_proven / formal_unproven / formal_legacy)。 + # 清单里写着定义、绑定、参数契约和验证/审阅引用,回看这次运行能对上是哪一份 + notes.append(("log", None, {**publication_info, "level": "info", "code": PUBLICATION_CODE, + "message": _publication_message(name, run_version, publication_info)})) + if catalog_changes: # 之后回看这次正式出具,能知道当时的目录和发布时不一样、差在哪几张表。每张表带 impact:direct 写死的 # SQL 用到的,possible Agent 可能查询的(界面分开说) notes.append((EventType.CATALOG_DRIFT, None, {"version": run_version, "count": len(catalog_changes), "tables": catalog_changes})) @@ -219,6 +246,10 @@ async def launch_run( payload_ev = dict(ev) node = payload_ev.pop("node_id", None) notes.append(("caliber.upgrade", node, payload_ev)) + if publication_info is not None: + # K07:这次正式运行固定了哪一份发布依据记进运行来源(运行行上的 origin 和 run.origin 事件是同一份): + # 「这次跑的是哪一版、哪份清单、什么身份」读运行的人一处就能看全。调用方给的来源键一个不动。 + origin = {**(origin or {}), "publication": publication_info} if origin_kind: from app.engine.origin import origin_note @@ -250,6 +281,17 @@ async def launch_run( return run +def _publication_message(name: str, version: int | None, info: Any) -> str: + """正式运行固定的发布依据写给人的一句话(`publication.pinned` 那条日志)。""" + identity = str((info or {}).get("identity") or "") + why = {"formal_proven": "发布依据齐全(覆盖这一版定义、绑定和取数语义,验证 matched 并经认证审阅确认全部指标)", + "formal_unproven": "这一版没有要求发布依据(资产不在证明范围内)", + "formal_legacy": "这一版是发布清单这一机制之前的资产,按原样发起"}.get(identity, identity) + manifest = str((info or {}).get("manifest") or "") + where = f",发布清单 {manifest[:12]}…" if manifest else "" + return f"本次正式运行固定「{name}」v{version}:{why}{where}" + + def graph_tool_names(graph: dict[str, Any]) -> list[str]: """图里绑定的工具名(去重,按出现顺序),能力快照和发布时记能力版本都按它取。模板拼出来的名字发起时还不知道是谁, 不算。图不成形时为空。""" diff --git a/backend/app/engine/nodes/llm.py b/backend/app/engine/nodes/llm.py index 03911cc7..4b036ba4 100644 --- a/backend/app/engine/nodes/llm.py +++ b/backend/app/engine/nodes/llm.py @@ -24,7 +24,6 @@ from app.engine.evidence import ( ledger_enabled, make_eid, next_exec, - query_entry_fields, schema_ledger_entry, ) from app.engine.expressions import CellError, cell_value, column_kind, locate_cell, numeric_text, same_value @@ -70,11 +69,12 @@ from app.tools.registry import ( args_model_of, build_tools, describe_args, + execution_id_of, guides_text, prepare_args, ) from app.tools.trust import asks_trustable, ask_gate, call_policy, node_task, trust_key_of -from app.capabilities.registry import is_platform_query, snapshot_owned +from app.capabilities.registry import is_platform_query, query_items, snapshot_owned # -------------------------------------------------------------------------- # 公共部分 @@ -353,6 +353,11 @@ async def _resolve_tools(ctx: NodeContext, state: GraphState, scope: AnalysisSco names = ctx.cfg("tools", []) or [] # 遮罩、只读的运行:记忆范围、知识库只认运行定下的,模型在参数里挑的也不算(tools/registry.ToolContext.fixed_scope) fixed = run_scope_fixed(ctx.run) + # K10:这次运行的类别、发起人与来源(发起时定下,恢复、接着跑沿用同一份)。caliber_query 按 run_class 选用途、 + # 用发起人当主体,并把来源带进派生的子运行;模型改不了这三样 + from app.engine.runner import RUN_OPTIONS_KEY + from app.tools.registry import RUN_CLASS_KEY, RUN_ORIGIN_KEY, RUN_STARTED_BY_KEY + tool_ctx = ToolContext( run_id=ctx.run.run_id, node_id=ctx.node.id, @@ -367,6 +372,10 @@ async def _resolve_tools(ctx: NodeContext, state: GraphState, scope: AnalysisSco catalog_view=catalog_view.of_run(ctx.run), # 数据源工具运行中途补固定版本时经它留一条事件(tools/datasource.py 的 _pin_late) emit=ctx.emit, + run_class=ctx.run.extra.get(RUN_CLASS_KEY), + started_by=ctx.run.extra.get(RUN_STARTED_BY_KEY), + run_options=dict(ctx.run.extra.get(RUN_OPTIONS_KEY) or {}), + origin=ctx.run.extra.get(RUN_ORIGIN_KEY), extra={ANALYSIS_SCOPE_KEY: scope} if scope is not None else {}, ) async with SessionLocal() as session: @@ -545,12 +554,17 @@ async def run_agent(state: GraphState, ctx: NodeContext) -> dict[str, Any]: snapshot_id = None # 查库成功时工具交回的 JSON 里带着查询快照的工件 id:记进返回值(进 checkpoint,重放拿到的 # 是同一份)和 tool.end(在封存范围内,证据接口从这里出发找快照)。只认平台执行的查询(数据源工具、 - # 能力登记里声明了表格的端点读取,is_platform_query 按名字认身份、不看结果长什么样):那个 id 是 - # 我们自己落的;MCP、自定义工具的文字来自外面,拼一个同样形状的 JSON 就能把任意快照塞进封存范围。 - # 端点读取另核一道:工件得是这次运行落下的端点快照 - query = query_entry_fields(content) if evidence_on and ok and is_platform_query(name) else None - if query and not await snapshot_owned(query["artifact"], ctx.run.run_id, name): - query = None + # K10 的口径查询 caliber_query、能力登记里声明了表格的端点读取,is_platform_query 按名字认身份、不看结果 + # 长什么样):那个 id 是我们自己落的;MCP、自定义工具的文字来自外面,拼一个同样形状的 JSON 就能把任意快照 + # 塞进封存范围。口径查询一次交回**多条**(queries 数组),这里逐条摊开、逐条核工件。 + queries: list[dict[str, Any]] = [] + if evidence_on and ok and is_platform_query(name): + for item in query_items(content, name): + artifact = str(item.get("artifact") or "") + # 端点读取、口径查询另核一道:工件得是这次运行(或它明确派生的子运行)落下的那一种快照 + if artifact and await snapshot_owned(artifact, ctx.run.run_id, name): + queries.append(item) + first = queries[0] if queries else None # 分析工具交回的结论工件:同查询快照,记进 tool.end(封存范围内),证据接口、时间线从这里认这一步的结论。另带一小段 # 判定(event_view:编号、算子、判定码、判定语……):preview 只是结论的前一截,判定语多半被截掉。编号和记台账时 # 交回模型的「【分析 An】」是同一个(_record_call 紧接着按同一个容器编),不记台账的执行没有编号 @@ -563,11 +577,13 @@ async def run_agent(state: GraphState, ctx: NodeContext) -> dict[str, Any]: duration_ms=elapsed, preview=content[:2000], artifact=snapshot_id, - **({"query_artifact": query["artifact"]} if query else {}), + **({"query_artifact": first["artifact"]} if first else {}), + # 一次调用交回多条查询(caliber_query)时把工件 id 全列出来:只给第一条,界面上剩下的就点不开 + **({"query_artifacts": [q["artifact"] for q in queries]} if len(queries) > 1 else {}), **({"analysis_artifact": analysis["artifact"], "analysis": event_view(analysis["result"], alias)} if analysis else {}), # 查询当时数据源的表结构快照:和查询快照一样落在封存范围内,证据接口从这里认它 - **({"schema_artifact": query["schema_artifact"]} if query and query.get("schema_artifact") else {}), + **({"schema_artifact": first["schema_artifact"]} if first and first.get("schema_artifact") else {}), # 这次查询的 SQL 检查结果单独带上:preview 截到前 2000 个字符,checks 通常在截掉的那段里 **({"checks": checks} if ok and name.startswith(QUERY_PREFIX) and (checks := event_checks(content)) else {}), **extra, @@ -579,7 +595,10 @@ async def run_agent(state: GraphState, ctx: NodeContext) -> dict[str, Any]: message=f"{name} 没有做成:{analysis['result'].get('reason') or '原因未知'}") outcome: dict[str, Any] = {"content": content, "ok": ok, "duration_ms": elapsed} if evidence_on: - outcome.update(snapshot=snapshot_id, query_artifact=query["artifact"] if query else None) + # 这次调用交回的全部查询(数据源一条;口径查询多条):一起进 checkpoint,重放取同一份,_record_call + # 据此逐条记台账——只留第一条,后面的查询就没了出处 + outcome.update(snapshot=snapshot_id, query_artifact=first["artifact"] if first else None, + queries=queries) return outcome @task @@ -790,7 +809,7 @@ async def run_agent(state: GraphState, ctx: NodeContext) -> dict[str, Any]: if evidence_on: # 编号只取决于 tool_step 的返回值(重放时取自 checkpoint),重放出来的还是这一套 content = _record_call(ctx.node.id, exec_no, call_id, name, args, outcome, record, - queries, entries, scope) + queries, entries, scope, run_id=ctx.run.run_id) transcript.append(record) messages.append(ToolMessage(content=content, tool_call_id=call_id)) if guard: @@ -940,12 +959,13 @@ async def run_agent(state: GraphState, ctx: NodeContext) -> dict[str, Any]: def _record_call(node_id: str, exec_no: int, call_id: str, name: str, args: dict[str, Any], outcome: dict[str, Any], record: dict[str, Any], queries: list[dict[str, Any]], - entries: list[dict[str, Any]], scope: AnalysisScope | None = None) -> str: + entries: list[dict[str, Any]], scope: AnalysisScope | None = None, run_id: str = "") -> str: """把一次执行过的工具调用记进台账、调用记录和本节点的查询清单,返回给模型看的内容。 查库成功的结果前面加一行「【证据 Q1】」:模型在循环里就知道每次查询的编号,cite_fields 抽取时照这个编号写出处。编号只在本节点内有效;报告目录里的 Q1… 按全局台账另编,两边 - 靠工件 id 对应,不靠编号。 + 靠工件 id 对应,不靠编号。一次调用交回多条查询(K10 的口径查询,queries 数组)时逐条编号, + 结果前面一行写全(「【证据 Q1、Q2】」),每条各记一条台账、各带自己的执行身份。 绑了分析工具的节点(scope):每次查询另往分析容器里放一份输入快照(编号同上);分析工具交回的结论记一条 kind analysis 的台账(contract.ledger_entry,带 call_id),编号 An,交回模型的换成「【分析 An】」那一段(app/tools/analysis.py)。 @@ -967,34 +987,78 @@ def _record_call(node_id: str, exec_no: int, call_id: str, name: str, args: dict entries.append(ledger_entry(found["result"], node_id=node_id, exec_no=exec_no, artifact=found["artifact"], call_id=call_id)) return reply_text(alias, found["result"]) - if not artifact or not is_platform_query(name): + items = _called_queries(outcome, content, name) + if not items: return content try: data = json.loads(content) except ValueError: data = None - fields = query_entry_fields(data) - if fields is None: - return content - alias = f"Q{len(queries) + 1}" - record.update(alias=alias, artifact=artifact) - # 表结构快照:同一件在本节点这次执行里只记一条 schema 条目。快照是内容寻址的,重放时读到的是同一份 - schema = fields.get("schema_artifact") - seen = schema and any(e.get("kind") == "schema" and e.get("artifact") == schema for e in entries) - frozen = None if not schema or seen else schema_ledger_entry(schema, node_id=node_id, exec_no=exec_no) - shaped = {"schema_artifact": schema, "tables": fields["tables"]} if seen or frozen else {} - entries.append({"kind": "query", "node_id": node_id, "exec": exec_no, "artifact": artifact, - **({"via": snapshot} if snapshot else {}), "call_id": call_id, "tool": name, - "source": fields["source"], "columns": fields["columns"], "rows": fields["rows"], - "truncated": fields["truncated"], **shaped}) - if frozen: - entries.append(frozen) - queries.append({"alias": alias, "call_id": call_id, "tool": name, "sql": str(args.get("sql") or ""), - "artifact": artifact, "via": snapshot, "columns": fields["columns"], - "rows": data.get("rows") or [], "truncated": fields["truncated"]}) - if scope is not None: - scope.add_query(alias, input_snapshot(data, ref=alias, artifact=artifact, node_id=node_id)) - return f"【证据 {alias}】\n{content}" + aliases: list[str] = [] + for item in items: + alias = f"Q{len(queries) + 1}" + aliases.append(alias) + artifact = str(item["artifact"]) + if "alias" not in record: + # 一次调用交回多条查询(K10 的口径查询)时,调用记录上记第一条:别的编号在同一行「【证据 Q1、Q2】」里 + record.update(alias=alias, artifact=artifact) + # 表结构快照:同一件在本节点这次执行里只记一条 schema 条目。快照是内容寻址的,重放时读到的是同一份 + schema = item.get("schema_artifact") + seen = bool(schema) and any(e.get("kind") == "schema" and e.get("artifact") == schema for e in entries) + frozen = None if not schema or seen else schema_ledger_entry(schema, node_id=node_id, exec_no=exec_no) + # 实际执行的执行身份(K10):query_id 是逻辑查询、execution_id 是这一次、attempt 是第几次。口径查询那条自己 + # 带着(K09 算好的),别的按这次调用的 id 或节点执行序号算 + identity = {"query_id": item.get("query_id") or node_id, + "execution_id": item.get("execution_id") or execution_id_of(node_id, attempt=exec_no, + call_id=call_id, + run_id=run_id), + "attempt": item.get("attempt") or exec_no} + entries.append({"kind": "query", "node_id": node_id, "exec": exec_no, "artifact": artifact, + **({"via": snapshot} if snapshot else {}), "call_id": call_id, "tool": name, + "source": item.get("source"), "columns": item["columns"], "rows": item["rows"], + "truncated": item["truncated"], **identity, + # 口径查询那条记下它在哪一版、哪张图、哪个取数节点:数据源查询没有这一项 + **({"origin": dict(item["origin"])} if item.get("origin") else {}), + # 复算要的材料(口径查询那条带着):参数输入哈希与源模板哈希,值本身不进台账 + **({"parameters": dict(item["parameters"])} if item.get("parameters") else {}), + **({"schema_artifact": schema, "tables": item.get("tables")} if seen or frozen else {})}) + if frozen: + entries.append(frozen) + # cite_fields 的摘要里要的是行数据:这次的结果里没有(口径查询不外发结果集)就按工件读一次,读不出来留空, + # 出处核对仍按工件取 + rows = data.get("rows") if isinstance(data, dict) and data.get("artifact") == artifact else None + queries.append({"alias": alias, "call_id": call_id, "tool": name, "sql": str(args.get("sql") or ""), + "artifact": artifact, "via": snapshot, "columns": item["columns"], + "rows": rows if rows is not None else _snapshot_rows(artifact), + "truncated": item["truncated"]}) + if scope is not None: + scope.add_query(alias, input_snapshot(data if isinstance(data, dict) else {}, ref=alias, + artifact=artifact, node_id=node_id)) + return f"【证据 {'、'.join(aliases)}】\n{content}" + + +def _called_queries(outcome: dict[str, Any], content: Any, name: str) -> list[dict[str, Any]]: + """这次调用记进台账的那几条查询:优先取 tool_step 交回的那一份(K10 的口径查询是多条),老 checkpoint 上只有 + query_artifact 一条时按结果自己摊开。非平台查询(MCP、自定义)返回空——拼一份同样形状的 JSON 不算证据。""" + if not is_platform_query(name): + return [] + items = [item for item in (outcome.get("queries") or []) if isinstance(item, dict) and item.get("artifact")] + if items: + return items + if not outcome.get("query_artifact"): + return [] + return query_items(content, name) + + +def _snapshot_rows(artifact: str) -> list[Any]: + """查询快照里的行(cite_fields 的摘要用)。读不出来就空:出处核对仍按工件取,不受影响。""" + from app.core import artifact_store + + try: + snapshot = artifact_store.load(artifact) + except ValueError: + return [] + return list(snapshot.get("rows") or []) if isinstance(snapshot, dict) else [] def _output_schema(ctx: NodeContext) -> dict[str, Any] | None: diff --git a/backend/app/engine/nodes/merge.py b/backend/app/engine/nodes/merge.py index 489fbefd..4ec2559c 100644 --- a/backend/app/engine/nodes/merge.py +++ b/backend/app/engine/nodes/merge.py @@ -11,6 +11,11 @@ query 的条目:报告照样按先后编成 Qn,[[v:Qn.rK.列]]、[[table:Qn **重放结果一致。** 快照里没有耗时这类每次不同的字段:节点重放、继续运行时同样的输入得到同一个工件 id、同一条 台账,报告里已经写下的出处不会因此变成另一份快照。 + +**服务端拼的语句不再被当模板。** 对账图里按维度值对齐的那条合并语句(ledger/reconcile 的 align_sql)由服务端拼成字面 +SQL,值来自查询结果、里面可能带 `{{ }}`:那种节点带参数契约(ledger/params 的 marker),契约里的 rendered_hash 与当前 +`sql` 对得上时这里的模板渲染跳过它——渲染一遍就是把数据当模板解释(K01 的二次渲染反例)。**核对过哈希才算**:节点被 +复制、sql 改过之后契约作废,照下面的正常渲染走。画布上自己写的合并 SQL 照旧支持 {{ }}(按运行输入筛日期)。 """ from __future__ import annotations @@ -26,6 +31,8 @@ from app.engine.context import NodeContext, NodeError from app.engine.evidence import ledger_enabled, next_exec from app.engine.merge_query import MERGE_SOURCE, MergeError, MergeInput, execute from app.engine.state import GraphState +from app.ledger import params as sql_params +from app.tools.registry import execution_id_of #: 合并警告进运行事件时的 code(log 事件)。运行详情、运行概况按它认出这是合并查询的警告 LOG_CODES = {"key_type_mismatch": "merge_key_type", "rows_grew": "merge_rows_grew", @@ -80,8 +87,14 @@ async def run_merge(state: GraphState, ctx: NodeContext) -> dict[str, Any]: inputs = ctx.config.get("inputs") if not isinstance(inputs, dict) or not inputs: raise NodeError(ctx.node.id, "「合并查询」还没有配置输入:至少选择一个上游的查询节点,并给它起一个别名") - # SQL 里允许 {{ }}(例如按运行输入筛日期),和 tool 节点的 SQL 一样先渲染;快照里存的是渲染之后、守卫规范过的那条 - sql = ctx.render_str(str(ctx.config.get("sql") or ""), state) + raw_sql = str(ctx.config.get("sql") or "") + if sql_params.is_literal(ctx.config, str(ctx.node.type)): + # 服务端拼好的字面语句(对账图里按维度值对齐的那条,ledger/reconcile),契约核对过哈希:里面的 {{ }} 是数据, + # 不再渲染一遍。契约过时(节点被复制、改过 sql)不在这里——那时 is_literal 为假,照下面的正常渲染走 + sql = raw_sql + else: + # SQL 里允许 {{ }}(例如按运行输入筛日期),和 tool 节点的 SQL 一样先渲染;快照里存的是渲染之后、守卫规范过的那条 + sql = ctx.render_str(raw_sql, state) loaded = [await _load_input(state, ctx, str(alias), node_id) for alias, node_id in inputs.items()] started = time.perf_counter() @@ -122,11 +135,16 @@ async def run_merge(state: GraphState, ctx: NodeContext) -> dict[str, Any]: output["column_types"] = outcome.column_types updates: dict[str, Any] = {"nodes": {ctx.node.id: output}} if ledger_enabled(ctx.run): - # 证据台账:和数据源查询同形的 query 条目,报告据此编 Qn;没有 via(外面不包工具快照) + # 证据台账:和数据源查询同形的 query 条目,报告据此编 Qn;没有 via(外面不包工具快照)。执行身份(K10): + # query_id 是这次合并(本节点),execution_id 按第几次执行——同一次运行里同样的合并跑两次也各不相同 + exec_no = next_exec(state, ctx.node.id) updates["evidence"] = [{ - "kind": "query", "node_id": ctx.node.id, "exec": next_exec(state, ctx.node.id), "artifact": artifact, + "kind": "query", "node_id": ctx.node.id, "exec": exec_no, "artifact": artifact, "source": MERGE_SOURCE, "columns": outcome.columns, "rows": len(outcome.rows), "truncated": outcome.truncated, + "query_id": ctx.node.id, "execution_id": execution_id_of(ctx.node.id, attempt=exec_no, + run_id=ctx.run.run_id), + "attempt": exec_no, }] var_name = str(ctx.config.get("assign_to") or "").strip() if var_name: diff --git a/backend/app/engine/nodes/metrics.py b/backend/app/engine/nodes/metrics.py index 693de465..154d2a44 100644 --- a/backend/app/engine/nodes/metrics.py +++ b/backend/app/engine/nodes/metrics.py @@ -6,6 +6,7 @@ import copy import json import math import re +from collections.abc import Iterable, Mapping from datetime import date, timedelta from typing import Any @@ -74,6 +75,21 @@ async def run_metrics(state: GraphState, ctx: NodeContext) -> dict[str, Any]: caliber_raw, caliber_version = pinned["caliber"], pinned["caliber_version"] if not definitions: raise NodeError(ctx.node.id, "口径卡没有定义任何指标") + # K08:卡上的指标 ID 要唯一——重复了不取第一条静默执行(下游按 ID 与位置取数,会分不清是哪一条)。带选择时 + # _pinned_caliber 的 require_selection 已经在过滤前拦过;这里管整卡(本地卡、转抄卡没给选择)那一路 + if duplicates := duplicate_metric_ids(definitions): + raise NodeError(ctx.node.id, f"口径卡上的指标 ID 重复了:{'、'.join(f'「{d}」' for d in duplicates)}。" + "同一张卡上的指标 ID 要唯一——下游按 ID 与位置取数,重复了分不清是哪一条," + "不能取第一条静默执行") + # K04:拿**实际生效的定义**和这张图里**真正要执行的那几个取数节点**上的受控绑定比。源头卡就是本地的指标; + # 转抄卡(caliber_from)是钉住那一版的定义,而且式子已经按 caliber_from.nodes 的源→本地映射改写到本图的节点 id + # (_pinned_caliber 的 rename_definition),所以本地那句被手工改过、还停在旧写法的 SQL 会被判中。对不上就在 + # 算数之前停:那条 SQL 算出来的是旧定义下的数,不能冒充新定义 + from app.ledger import bindings + + alignment = bindings.analyze(ctx.run.spec.model_dump(mode="json"), ctx.node.id, definitions) + if alignment.blocked: + raise NodeError(ctx.node.id, "口径卡的业务定义和取数 SQL 对不上,没有计算任何指标:" + alignment.reason) # 定义的内容指纹(data/caliber_identity):同一位置的口径定义变没变按它认,运行时算出来的值不进哈希。 # 口径名和版本不参与(这里只按指标算),和账本里的源头口径卡两侧对得上 definition_hash = card_hash_of({"metrics": definitions}) @@ -375,8 +391,10 @@ async def run_metrics(state: GraphState, ctx: NodeContext) -> dict[str, Any]: sources.append(snap) metric["contract_findings"] = list(dict.fromkeys([*(metric.get("contract_findings") or []), *contract_findings(definition, metric, sources)])) - # 描述文字不会被静默当作已执行的 SQL 约束。 - if any(definition.get(key) for key in ("grain", "time_field", "numerator", "denominator", "dimensions", "filters", "params")): + # 描述文字不会被静默当作已执行的 SQL 约束。业务字段(K04 的时间口径、退款规则)也算:受控绑定对齐只说 + # 「定义和取数实现同步」,业务描述本身仍需人工审阅(4.5),质量结论不能因为 aligned 自动变成 pass + if any(definition.get(key) for key in ("grain", "time_field", "numerator", "denominator", "dimensions", + "filters", "params", "time_role", "refund_rule")): metric["semantic_unverified"] = True metric["quality"] = metric_quality(metric) semantic_fingerprint = semantic_hash(ctx.run.spec.model_dump(mode="json"), ctx.node.id) @@ -447,13 +465,106 @@ async def run_metrics(state: GraphState, ctx: NodeContext) -> dict[str, Any]: return updates +# -------------------------------------------------------------------------- +# 指标选择(K08):caliber_from.metrics 是可选选择,缺省整卡 +# -------------------------------------------------------------------------- + + +class SelectionRefused(ValueError): + """口径卡的指标选择读不出来(形状不对、空的、点了卡上不存在的指标):响亮失败,绝不退回整卡。 + + 退回整卡等于没选——算的是别的指标、下游按位置取的 `nodes.<卡>.metrics[i]` 也就对不上了。所以这里不静默放宽。""" + + +def duplicate_metric_ids(definitions: Iterable[Any]) -> list[str]: + """卡上**重复出现的非空指标 id**(按首次出现顺序,每个只列一次)。 + + 指标 id 在一张卡上该唯一:下游 `nodes.<卡>.metrics[i]`、出具契约、比例契约、报告引用都按 id 与位置取数,同一张卡上 + 两个指标同名就分不清是哪一条。**不能取第一条静默执行**——那会把另一条的数顶替过来。空 id(没有声明的)不算重复, + 缺 id 另有报法(画布校验 metrics.id_missing、运行时报「指标定义不完整」)。 + + 判定只有一处:``ledger.closure.duplicate_metric_ids``(闭包把它记成 DUPLICATE_METRIC_ID 未决,运行时/画布校验按同一份 + 依据响亮失败——两边不会一个拦一个放)。""" + from app.ledger.closure import duplicate_metric_ids as canonical + + return list(canonical(list(definitions))) + + +def selection_index(definitions: Iterable[Any], selection: Any = None) -> list[int]: + """有效指标在 ``definitions`` 里的**下标**(按卡顺序)。``selection`` 缺省 → 全部下标。 + + 位置与取舍只由 ``ledger.closure.selection_index`` 这一处算(K08 的一份解释),这里只是取它的 ``positions``:运行时、 + 对账、召回认 ``nodes.<卡>.metrics[i]`` 的 i 时都走它,别处不再各写一遍筛选与排序。""" + from app.ledger.closure import selection_index as canonical + + return list(canonical(list(definitions), selection).positions) + + +def effective_metrics(definitions: Iterable[Any], selection: Any = None) -> list[Any]: + """这次真正要算的指标定义(按**卡顺序**归一)。``selection`` 缺省(``None``)→ 整卡原样,行为一字不变。 + + 唯一的一份解释在 ``ledger.closure.effective_metrics``(位置与取舍同一处算);这里只是转发,别处不再各写一遍。""" + from app.ledger.closure import effective_metrics as canonical + + return list(canonical(list(definitions), selection)) + + +def require_selection(definitions: Iterable[Any], selection: Any) -> list[Any]: + """运行时按口径卡上记的选择(``caliber_from.metrics``)读这一次真正要算的定义,未知、空的选择响亮失败。 + + ``ledger.closure.selection_index`` 把选择里认不出的 id 照实交回(不静默当整卡、也不静默丢掉):这里把它变成一条 + 能看懂的 NodeError 由调用方抛。空选择(显式 ``[]``,或选择里没有一个是这张卡上的)同样不许——不退成整卡。""" + from app.ledger.closure import selection_index as canonical + + if isinstance(selection, (str, bytes)) or not isinstance(selection, (list, tuple)): + raise SelectionRefused("要写成一串指标 id") + if any(not isinstance(s, str) or not s.strip() for s in selection): + raise SelectionRefused("每一项都要是非空的指标 id") + # 卡上同名指标(重复 id):闭合解析只取第一次,绝不能顺着它把第一条静默算出来顶替另一条——在这里响亮失败 + if duplicates := duplicate_metric_ids(definitions): + raise SelectionRefused(f"这张卡上有重复的指标 ID:{'、'.join(f'「{d}」' for d in duplicates)}" + "(指标 ID 要唯一,重复了分不清取的是哪一条)") + index = canonical(list(definitions), selection) + card_ids = [str(m.get("id")) for m in definitions if isinstance(m, Mapping) and m.get("id")] + if index.unknown: + raise SelectionRefused(f"这张卡上没有指标 {'、'.join(f'「{u}」' for u in index.unknown)}" + f"(卡上的指标:{'、'.join(card_ids) or '(一个也没有)'})") + if not index.definitions: + raise SelectionRefused("一个指标也没选:不给就按整卡算,给了空列表不当作整卡") + return list(index.definitions) + + +def pinned_effective(pinned: Any) -> list[dict[str, Any]]: + """一张已读好的口径卡(ledger.derive.Pinned)**这次真正会算出的**指标数组:``effective_metrics(pinned.metrics, 选择)``。 + + 对账、召回按 ``nodes.<卡>.metrics[i]`` 建引用、配列时只用这一份:卡带了指标选择(caliber_from.metrics,K08)时, + 全量定义里的下标和运行时算出来那份对不上,照全量定下标会静默取到别的指标。没有选择时就是全量定义(行为一字不变)。 + + 选择从哪来(K08 S2):裁剪过的 ``Pinned.closure``(``derive.select_pinned`` 附的这一次选择)优先;没有闭包时看 + ``Pinned.selection``、再看卡自己的 ``caliber_from.metrics``。""" + selection: Any = None + closure = getattr(pinned, "closure", None) + if closure is not None and not getattr(closure, "whole_card", True): + selection = list(getattr(closure, "metric_ids", ()) or ()) + else: + selection = getattr(pinned, "selection", None) + if selection is None: + config = getattr(pinned, "card_config", None) + ref = config.get("caliber_from") if isinstance(config, dict) else None + selection = ref.get("metrics") if isinstance(ref, dict) else None + return effective_metrics(list(pinned.metrics), selection) + + async def _pinned_caliber(ctx: NodeContext) -> tuple[dict[str, Any], dict[str, Any]]: """caliber_from 指向的那张口径卡:({caliber, caliber_version, metrics}, 来源)。 从那个工作流的 WorkflowVersion 快照里取——版本快照不可变,同一份引用每次取到的定义都一样, 审批恢复后节点重放也还是这一份。取不到就让节点失败并说清是哪一环断了:悄悄退回本地 定义,等于换了口径还照常出具。 - """ + + **普通使用者先过资产授权这一道**(`_require_own_caliber`,K14):图是使用者的(问数据里生成的图也是),光在发起时按图 + 的白名单拦一遍不够——「读别的工作流那一版的口径定义」这件事真正的门在这一层。没有授权在**读定义之前**就失败(`format` + 写错那种不涉及定义,照旧直接说格式)。""" from sqlalchemy import select from app.db.base import SessionLocal @@ -467,6 +578,7 @@ async def _pinned_caliber(ctx: NodeContext) -> tuple[dict[str, Any], dict[str, A if not wf_id or not node_id or version is None or version < 1: raise NodeError(ctx.node.id, f"「{field_label('caliber_from')}」格式有误:需要指定工作流、版本和其中的口径卡," f"当前为「{ref}」") + await _require_own_caliber(ctx, workflow_id=wf_id, version=version) async with SessionLocal() as session: workflow = await session.get(Workflow, wf_id) if workflow is None: @@ -506,10 +618,58 @@ async def _pinned_caliber(ctx: NodeContext) -> tuple[dict[str, Any], dict[str, A raise NodeError(ctx.node.id, f"「{field_label('caliber_from')}」的节点改名映射有误:{problem}") metrics = [rename_definition(m, rename) for m in metrics] source["nodes"] = dict(rename) + # K08:可选指标选择(caliber_from.metrics)。缺省整卡;给了就只算选中的那些(按卡顺序归一)——未知、空的响亮失败, + # 绝不退回整卡。绑定判定(run_metrics 拿这一份 definitions 去比对)、指标集、下游按位置取的 nodes.<卡>.metrics[i] + # 都按这一份有效数组(唯一的一份解释在 ledger.closure,见 effective_metrics) + selection = ref.get("metrics") if isinstance(ref, dict) else None + if selection is not None: + try: + metrics = require_selection(metrics, selection) + except SelectionRefused as e: + raise NodeError(ctx.node.id, f"「{field_label('caliber_from')}」的指标选择(metrics)用不了:{e}") from e + source["metrics"] = [str(m.get("id")) for m in metrics] return {"caliber": cfg.get("caliber") or title, "caliber_version": str(cfg.get("caliber_version") or "v1"), "metrics": metrics}, source +async def _require_own_caliber(ctx: NodeContext, *, workflow_id: str, version: int) -> None: + """普通使用者拿 `caliber_from` 钉别的工作流那一版的口径卡时,运行时按**同一份资产授权**核一遍(K14)。 + + 为什么必须在运行时再判一道:图是使用者自己的(问数据里模型生成的图、画布上搭的图都一样),发起时的白名单只认节点类型, + 认不出「这一版口径是谁的」——`caliber_from` 把**任意一份已发布口径的定义**读进这次运行这件事,只有执行到这一步才知道。 + 所以门设在这里:`apps/access.caliber_role`(AppGrant + 应用当前发布版精确固定着这一版)到 use 及以上才放行; + builder / admin / 关登录由 `restricted_actor` 显式放行(这几档不写进资产授权函数)。没授权在**读定义之前**失败—— + 既不把那份口径读出来,也不算任何指标(机器码 `querycore_not_authorized`,和别处同一条口径的拒绝同一个码)。 + + 判谁:**父 Run 记下来的发起人**(名字),加上请求上下文里那个认得出名字的身份(调用方替谁发起时取更严的那一个)。 + **两者都没有**说明这次运行不是某个使用者发起的(服务端自己发起的按需比对、口径召回、目录变化后的重算:`ledger/reconcile`、 + `ledger/recall` 这批不带 actor,调度器、发布之后的后台任务也一样)——那不是「使用者拿别人的口径定义」,不按使用者那一档 + 收窄(builder 路径照旧跑得完)。""" + from app.api.deps import Principal, current_principal + from app.apps.access import at_least, caliber_role + from app.auth.chat_policy import restricted_actor + from app.db.base import SessionLocal + from app.ledger.querycore import NOT_AUTHORIZED + from app.tools.registry import RUN_STARTED_BY_KEY + + extra = ctx.run.extra if isinstance(ctx.run.extra, dict) else {} + who: Any = extra.get(RUN_STARTED_BY_KEY) + if not who: + request = current_principal() + if not isinstance(request, Principal) or not request.username: + return + who = request + async with SessionLocal() as session: + if not await restricted_actor(session, who): + return + role = await caliber_role(session, who, str(workflow_id), int(version)) + if at_least(role, "use"): + return + raise NodeError(ctx.node.id, "没有权限:这张卡转抄的口径没有授权给你使用,没有读它的定义、也没有算任何指标" + f"({NOT_AUTHORIZED})。要用它先让搭建者把固定着那一版的「应用」授权给你," + "或者按数据源自己搭一张图") + + #: 改名映射里的节点 id:要能写进式子的取值链(nodes.),和画布上的节点 id 同一种写法 _NODE_ID = re.compile(r"^[A-Za-z_][\w-]*$") diff --git a/backend/app/engine/nodes/multi.py b/backend/app/engine/nodes/multi.py index eefdf394..481e0a1d 100644 --- a/backend/app/engine/nodes/multi.py +++ b/backend/app/engine/nodes/multi.py @@ -18,6 +18,7 @@ from app.db.models import Workflow from app.engine.context import ( LABEL_PREFIX_KEY, PREFIX_KEY, STREAM_KEY, NodeContext, NodeError, stream_writer, ) +from app.engine.evidence import ledger_enabled, next_exec from app.engine.lineage import whole_ref from app.engine.state import GraphState, message_text, template_context from app.engine.toolcalls import ( @@ -316,8 +317,9 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: async def _member(name: str, instruction: str, progress: str, tally: dict[str, Any]) -> dict[str, Any]: cfg = agent_map[name] - # 绑了分析工具的成员:这一次执行自己的分析容器(同 Agent 节点)。查询结果照 Agent 的写法编成「【证据 Qn】」,分析结论 - # 编成「【分析 An】」;协作节点不记证据台账,这些编号只给成员自己接着分析、下钻用 + # 绑了分析工具的成员:这一次执行自己的分析容器(同 Agent 节点)。查询结果照 Agent 的写法编成「【证据 Qn】」(一次 + # 调用交回多条时逐条编号),分析结论编成「【分析 An】」;协作节点不记证据台账,这些编号只给成员自己接着分析、 + # 下钻用——每个编号对应的逻辑查询与执行身份记在这次调用的调用记录里,随团队产出一起封存 scope = (AnalysisScope(node_id=ctx.node.id, snapshot=run_snapshot(ctx.run)) if any(is_analysis_tool(t) for t in cfg.get("tools", []) or []) else None) async with SessionLocal() as session: @@ -329,6 +331,11 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: max_tokens=int(cfg.get("max_tokens") or 4096), ), ) + # K10:这次运行的类别、发起人与来源照运行记录来——成员绑的 caliber_query 和调用工具节点、Agent、别条路 + # 上拿到同一个答案(formal 父 Run 走 formal judge、用发起人当主体、把固定的数据版本与选项带进派生的子运行) + from app.engine.runner import RUN_OPTIONS_KEY + from app.tools.registry import RUN_CLASS_KEY, RUN_ORIGIN_KEY, RUN_STARTED_BY_KEY + tool_ctx = ToolContext( run_id=ctx.run.run_id, node_id=f"{ctx.node.id}:{name}", @@ -343,6 +350,10 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: catalog_view=catalog_view.of_run(ctx.run), # 数据源工具运行中途补固定版本时经它留一条事件(tools/datasource.py 的 _pin_late) emit=ctx.emit, + run_class=ctx.run.extra.get(RUN_CLASS_KEY), + started_by=ctx.run.extra.get(RUN_STARTED_BY_KEY), + run_options=dict(ctx.run.extra.get(RUN_OPTIONS_KEY) or {}), + origin=ctx.run.extra.get(RUN_ORIGIN_KEY), extra={ANALYSIS_SCOPE_KEY: scope} if scope is not None else {}, ) tools = await build_tools(cfg.get("tools", []) or [], tool_ctx, session=session) @@ -357,6 +368,12 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: HumanMessage(content=f"团队目标:{goal}\n\n已有进展:\n{progress or '(无)'}\n\n你的任务:{instruction}"), ] calls: list[dict[str, Any]] = [] + # K10 收尾:成员这一次查到的数进不进运行封存证据(子工作流转发那一套的同一个位置:node.finished 的 evidence)。 + # 升级前发起的运行一个字都不加(ledger_enabled,同 tools/llm 的 evidence_on);模版拼出来的普通工具调用 + # (calculator 这类)不是平台执行的查询,entry 一个都不产生,产出与以前一字不差 + evidence_on = ledger_enabled(ctx.run) + entries: list[dict[str, Any]] = [] + exec_no = next_exec(state, ctx.node.id) if evidence_on else 0 # 和 agent 节点同一个硬顶:成员上配多少步都过不去 max_agent_steps max_steps = min(int(cfg.get("max_steps") or 4), settings.max_agent_steps) nudged = False @@ -372,12 +389,13 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: text = message_text(reply) snippet = leaked_markup(text) if not snippet: - return {"text": text, "tool_calls": calls} + return {"text": text, "tool_calls": calls, **_member_evidence(entries)} # 把工具调用写成了文字:这一步什么都没查到。纠正一次,还这样就记为失败, # 原因交给调度者——以前这段标记会被当成这个成员的结论交上去 if nudged: return {"text": f"({name} 这一步执行失败:{MEMBER_MARKUP_FAILED})", - "tool_calls": calls, "failed": True, "error": MEMBER_MARKUP_FAILED} + "tool_calls": calls, "failed": True, "error": MEMBER_MARKUP_FAILED, + **_member_evidence(entries)} nudged = True ctx.emit(EventType.LOG, level="warn", code="tool_markup_leak", message=f"{markup_warning(snippet, name)},已要求模型重试一次") @@ -471,9 +489,13 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: reason_code=analysis["result"].get("reason_code"), reason=analysis["result"].get("reason"), message=f"{name} 的 {tname} 没有做成:{analysis['result'].get('reason') or '原因未知'}") - calls.append({"tool": tname, "args": targs, "result": content[:2000]}) - if scope is not None and not failure and tname in tool_map: - content = await _numbered(scope, tname, content, analysis, ctx.run.run_id, ctx.node.id) + record = {"tool": tname, "args": targs, "result": content[:2000]} + if not failure and tname in tool_map and (scope is not None or evidence_on): + content = await _numbered(scope, tname, content, analysis, ctx.run.run_id, ctx.node.id, + call_id=cid, member=name, exec_no=exec_no, + record=record if evidence_on else None, + ledger=entries if evidence_on else None) + calls.append(record) messages.append(ToolMessage(content=content, tool_call_id=cid)) # 步数用完了:最后一步一定是要了工具的,模型从没拿到过"说结论"的那一轮。 @@ -500,7 +522,8 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: if snippet := leaked_markup(text): if not calls: return {"text": f"({name} 这一步执行失败:{MEMBER_MARKUP_FAILED})", - "tool_calls": calls, "failed": True, "error": MEMBER_MARKUP_FAILED} + "tool_calls": calls, "failed": True, "error": MEMBER_MARKUP_FAILED, + **_member_evidence(entries)} # 真调过工具,只是收尾轮还想接着查:取它之前说过的话,和 agent 节点一样 ctx.emit(EventType.LOG, level="warn", code="tool_markup_leak", message=f"{markup_warning(snippet, name)}:已达步数上限,收尾时仍试图调用工具") @@ -509,7 +532,8 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: and not leaked_markup(t)), "") ctx.emit(EventType.LOG, level="warn", code="step_limit_settled", message=f"{name} 已用完 {max_steps} 步上限,结论基于已查到的部分") - return {"text": text or f"({name} 已用完 {max_steps} 步上限,未给出结论)", "tool_calls": calls} + return {"text": text or f"({name} 已用完 {max_steps} 步上限,未给出结论)", "tool_calls": calls, + **_member_evidence(entries)} progress_lines: list[str] = [] final_text = "" @@ -517,6 +541,10 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: #: 失败说明是写给调度者看的,不是结论 delivered: list[tuple[str, str]] = [] rounds_meta: list[dict[str, Any]] = [] + #: 成员实际查到的数:这一次执行里各成员交回的 query 条目(K10 收尾)。随这个节点的 node.finished 进运行封存证据, + #: 让证据面板、导出包、运行对比、双盲复算读得到成员查过什么。从**缓存下来的成员产出**里取(work 是 task):重放 + #: 拿到的还是同一批条目,不会因为重跑一次多记或少记。普通成员(没查过库)一条都没有,产出与以前一字不差 + ledger: list[dict[str, Any]] = [] #: 调度者最后一轮给的理由,以及派过活的成员。轮数用完时报错要说清卡在哪、谁从没上过场 last_reason = "" dispatched: set[str] = set() @@ -561,6 +589,10 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: if spent: _accumulate(spent) each_ms = int(outcome.pop("duration_ms", 0) or 0) + # 成员的查询条目交给这个节点去记(不进 transcript:产出里那一条已经带着编号与执行身份) + found = outcome.pop("evidence", None) + if isinstance(found, list): + ledger += [e for e in found if isinstance(e, dict)] sum_ms += each_ms progress_lines.append(f"【{name}】{outcome['text']}") transcript.append( @@ -641,6 +673,13 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: "nodes": {ctx.node.id: result}, "usage": usage_total, } + if ledger: + # 成员查到的数进运行封存证据:node.finished 的 evidence(这一份进封存范围,封存读取、导出包的来源与遮罩判断、 + # 运行对比、双盲复算都从这里认),条目带成员的节点前缀(「协作节点 id:成员名」,和成员查库时记在工件上的那个 + # 节点一致)。不带「协作节点 id/成员名」那种前缀:那是子工作流转发的写法,_own_evidence 会把它当成子图里节点 + # 自己记过的、从这个节点的事件里滤掉(engine/compiler.py),这些条目就没进封存;而 _own_evidence 放行的又必须 + # 是祖先节点或「祖先/…」,所以「节点:成员」既进封存、又不进报告目录的 Q 编号(见 _numbered 的说明) + updates["evidence"] = ledger if ctx.cfg("emit_message", True): updates["messages"] = [AIMessage(content=final_text or "(空)")] var_name = ctx.cfg("assign_to", "") @@ -649,23 +688,90 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: return updates -async def _numbered(scope: AnalysisScope, tool: str, content: str, analysis: dict[str, Any] | None, run_id: str, - node_id: str) -> str: - """绑了分析工具的协作成员:一次成功的工具调用交回成员的内容。数据源查询(平台执行的,端点读取另核工件是这次运行落下 - 的)编号「【证据 Qn】」并放进分析容器;分析结论编号「【分析 An】」、换成给模型看的那一段。别的工具原样。""" - from app.capabilities.registry import is_platform_query, snapshot_owned - from app.engine.evidence import query_entry_fields +def _member_evidence(entries: list[dict[str, Any]]) -> dict[str, Any]: + """成员这一次执行记下的查询条目(没有就一个键都不加:普通成员的产出与以前一字不差)。""" + return {"evidence": list(entries)} if entries else {} + + +async def _platform_queries(content: str, tool: str, run_id: str) -> list[dict[str, Any]]: + """这次工具调用交回、**可以作证**的查询条目:按身份摊开(capabilities.registry.query_items——数据源查询一条、 + 口径查询是 queries 数组里**多条**),逐条认工件(snapshot_owned:数据源查询的快照由数据层自己落,照旧放行;口径 + 查询那条必须是这次运行或它明确派生的子运行落下的查询快照)。不是平台执行的查询返回空——拼一份同样形状的 JSON + 不算证据;伪造的、别的运行落的、别的种类的一律不要。抽取与认工件和 Agent 节点、调用工具节点是同一份。""" + from app.capabilities.registry import is_platform_query, query_items, snapshot_owned + + if not is_platform_query(tool): + return [] + out: list[dict[str, Any]] = [] + for item in query_items(content, tool): + artifact = str(item.get("artifact") or "") + if artifact and await snapshot_owned(artifact, run_id, tool): + out.append(item) + return out + + +async def _numbered(scope: AnalysisScope | None, tool: str, content: str, analysis: dict[str, Any] | None, + run_id: str, node_id: str, *, call_id: str = "", member: str = "", exec_no: int = 0, + record: dict[str, Any] | None = None, ledger: list[dict[str, Any]] | None = None) -> str: + """一次成功的工具调用交回成员的内容。平台执行的查询(数据源查询、K10 的口径查询 caliber_query、登记里声明了表格的 + 端点读取)编号「【证据 Qn】」并放进成员自己的分析容器(scope 给了才做——绑了分析工具的成员才有容器,没绑的成员看到的 + 内容一个字不改);分析结论编号「【分析 An】」、换成给模型看的那一段。别的工具原样。 + + **一次调用交回多条查询**(口径查询的结果里是 queries 数组)时逐条编号、逐条放进容器:抽取与认工件走和数据源查询、 + Agent 节点、调用工具节点**同一份**(_platform_queries),不另写一套按结果长相猜的逻辑,也不因为带的是数组就只认 + 第一条。伪造的、别的运行落的、不是查询快照的工件一律不进容器、不进台账。 + + ledger 给了就逐条往它上面记一条运行台账的 query 条目(和 tools/llm 记的那一种同形:工件、来源、列与行数、截断、 + query_id/execution_id/attempt,口径查询那条另带 origin/parameters,另带 member=哪个成员),由调用方作为这个节点的 + evidence 交出去、随 node.finished 进封存。条目上的节点 id 是「协作节点 id:成员名」——带成员归属,又不会被 + engine/compiler 的 _own_evidence 当成子工作流转发的条目滤掉(那种前缀是「协作节点 id/成员名」,滤掉就进不了封存)。 + 封存读取(engine/evidence_reader 的 queries / query_records / entries)、导出包的来源与遮罩判断、运行对比、双盲复算 + 的原始编号都从这里认;报告目录按祖先收证据(report.report_catalog 的 allowed)不收它,所以报告里的全局 Q 编号与 + 面板按报告引用的那一份一个字不变,成员查到的数是**附加**在封存证据上的(证据面板按报告引用列的那份仍只有报告引过的)。 + + record 是这次调用的调用记录(进团队产出、随运行封存):编号只活在成员自己的容器里,记下 alias / query_id / + execution_id / attempt 才看得出这个 Qn 是哪一次执行的哪条查询。执行身份同 tools/registry.execution_id_of。""" + from app.tools.registry import execution_id_of if analysis is not None: return reply_text(scope.add_result(analysis["result"], analysis["artifact"]), analysis["result"]) - if not is_platform_query(tool): + items = await _platform_queries(content, tool, run_id) + if not items: return content - fields = query_entry_fields(content) - if fields is None or not await snapshot_owned(fields["artifact"], run_id, tool): - return content - alias = f"Q{len(scope.queries) + 1}" - scope.add_query(alias, input_snapshot(json.loads(content), ref=alias, artifact=fields["artifact"], node_id=node_id)) - return f"【证据 {alias}】\n{content}" + data = json.loads(content) + aliases: list[str] = [] + traced: list[dict[str, Any]] = [] + owner = f"{node_id}:{member}" if member else node_id + for item in items: + artifact = str(item["artifact"]) + alias = "" + if scope is not None: + alias = f"Q{len(scope.queries) + 1}" + aliases.append(alias) + scope.add_query(alias, input_snapshot(data if isinstance(data, dict) else {}, ref=alias, + artifact=artifact, node_id=node_id)) + # 实际执行的执行身份(K10):query_id 是逻辑查询、execution_id 是这一次、attempt 是第几次。口径查询那条自己 + # 带着(K09 算好的),别的按这次调用的 id 算 + identity = {"query_id": item.get("query_id") or node_id, + "execution_id": item.get("execution_id") or execution_id_of(node_id, attempt=exec_no, + call_id=call_id, run_id=run_id), + "attempt": item.get("attempt") or exec_no or 1} + traced.append({"artifact": artifact, **({"alias": alias} if alias else {}), **identity}) + if ledger is not None: + # 运行台账的 query 条目:和 tools/llm 记的那一种同形(工件、来源、列与行数、截断、执行身份), + # 口径查询那条另带 origin(哪一版、哪张图、哪个取数节点)与 parameters(输入/模板哈希,值本身不在) + ledger.append({ + "kind": "query", "node_id": owner, "exec": exec_no or 1, "artifact": artifact, + "call_id": call_id, "tool": tool, "member": member, + "source": item.get("source"), "columns": [str(c) for c in item.get("columns") or []], + "rows": int(item.get("rows") or 0), "truncated": bool(item.get("truncated")), **identity, + **({"origin": dict(item["origin"])} if isinstance(item.get("origin"), dict) else {}), + **({"parameters": dict(item["parameters"])} if isinstance(item.get("parameters"), dict) else {}), + }) + if record is not None: + record.update(artifact=str(items[0]["artifact"]), queries=traced, + **({"alias": traced[0]["alias"]} if traced[0].get("alias") else {})) + return f"【证据 {'、'.join(aliases)}】\n{content}" if aliases else content # -------------------------------------------------------------------------- diff --git a/backend/app/engine/nodes/tools.py b/backend/app/engine/nodes/tools.py index 17b3e257..7f681e24 100644 --- a/backend/app/engine/nodes/tools.py +++ b/backend/app/engine/nodes/tools.py @@ -12,16 +12,18 @@ from langgraph.func import task from app.core.artifact_store import canonical_json, content_hash from app.engine.approval import read_decision from app.engine.context import NodeContext, NodeError, NodeRejected -from app.engine.evidence import ledger_enabled, next_exec, query_entry_fields, schema_ledger_entry +from app.engine.evidence import ledger_enabled, next_exec, schema_ledger_entry +from app.engine.expressions import render_deep from app.engine.replay import ask, once -from app.engine.state import GraphState +from app.engine.state import GraphState, template_context from app.engine.toolcalls import ToolTimeout, limit_fields, limit_of, run_bounded from app.sandbox.base import SandboxLimits from app.sandbox.manager import sandbox_manager from app.engine.sql_problems import event_checks -from app.capabilities.registry import is_platform_query, snapshot_owned +from app.capabilities.registry import is_platform_query, query_items, snapshot_owned from app.data import catalog_view -from app.tools.datasource import (DATA_UNAVAILABLE, SCHEMA_PREFIX, run_masks_results, run_reads_only, +from app.ledger import params as sql_params +from app.tools.datasource import (DATA_UNAVAILABLE, QUERY_PREFIX, SCHEMA_PREFIX, run_masks_results, run_reads_only, run_scope_fixed, run_versions) from app.tools.registry import ( ToolArgsError, @@ -30,6 +32,7 @@ from app.tools.registry import ( build_tools, call_is_dangerous, call_tool, + execution_id_of, get_spec, ) from app.tools.trust import ask_gate, asks_trustable, call_policy, node_task @@ -40,11 +43,62 @@ from app.tools.trust import ask_gate, asks_trustable, call_policy, node_task QUERY_FAILED = ("查询失败:", "SQL 被拒绝:", DATA_UNAVAILABLE) #: code 节点在证据链里的角色:取数(产出本身就是源数据)还是计算。缺省按计算算 EVIDENCE_ROLES = ("source", "compute") +#: 参数不完整(缺参数 / 未声明 / 认不出的写法)时的说法:说出来,并且明确没发出查询(ledger/params 的机器码在 reason 里) +PARAMETER_INCOMPLETE = "工具 {tool} 的 SQL 参数不完整,没有发出查询:{reason}" + + +def _entry_fields(ctx: NodeContext) -> dict[str, dict[str, Any]]: + """这张图的入口节点声明的字段(名字 → 字段)。运行时判「未声明参数」和记参数类型都用它。""" + from app.engine.schema import NodeType + + out: dict[str, dict[str, Any]] = {} + for node in ctx.run.spec.nodes: + if node.type != NodeType.INPUT: + continue + for f in node.config.get("fields") or []: + if isinstance(f, dict) and isinstance(f.get("name"), str) and f["name"].strip(): + out.setdefault(f["name"].strip(), dict(f)) + return out + + +def _tool_args(ctx: NodeContext, state: GraphState, name: str) -> tuple[Any, dict[str, Any] | None]: + """这一次调用工具的参数,以及查询快照要记的参数材料(ledger/params)。 + + 带参数契约的节点(组合式问数、对账图写,见 ledger/params 的 marker):args 里已经是渲染好的字面语句——值渲染进去的 + 那一次已经发生过——运行时的模板渲染一概不碰它,材料直接取节点上那一份(源模板哈希、参数类型)。不然值里的 + `{{ vars.question }}` 会被当成模板替换成那个变量的值,SQL 被数据改掉(K01 的二次渲染反例)。契约要**核对过哈希**才算 + (is_literal):节点被复制、改过 args 之后,契约作废,这里照别的节点一样正常渲染、正常判参数。 + + 别的节点照旧:用当前状态渲染。数据源查询在发出前过一遍参数完整性:模板里的 {{ input.字段 }} 这次取不到值(没给、 + 也没缺省值;或压根没声明)就不发查询。以前这种情况渲染成空串照发,`AND region = ''` 从哪来都看不出来。 + """ + config = ctx.config if isinstance(ctx.config, dict) else {} + raw = ctx.cfg("args", {}) or {} + if sql_params.is_literal(config, str(ctx.node.type)): + # 契约核对过(args 还是服务端渲染好的那一条):不再渲染,材料照契约记 + return raw, sql_params.marker_material(config, str(ctx.node.type)) + values = dict(state.get("input") or {}) + template = str(raw.get("sql") or "") if isinstance(raw, dict) else "" + material: dict[str, Any] | None = None + # 按 input 取值的地方要过参数完整性:认得出字段的(点号/合法下标)判缺参、未声明,认不出的写法(会渲染成空串) + # 直接拒——两种都不能漏掉,所以门是 mentions_input 而不是「有没有认得出的字段」 + if template and sql_params.mentions_input(template): + fields = _entry_fields(ctx) + if name.startswith(QUERY_PREFIX): + if problems := sql_params.runtime_problems(template, values=values, declared=fields): + raise ToolArgsError(PARAMETER_INCOMPLETE.format(tool=name, reason=sql_params.describe(problems))) + material = sql_params.material(template, values=values, declared_fields=fields) + return render_deep(raw, {**template_context(state), "input": values}), material def _tool_ctx(ctx: NodeContext) -> ToolContext: # 遮罩、只读的运行:记忆范围、知识库只认运行定下的,节点配置、图级 defaults 里写的都不算(tools/registry.ToolContext.fixed_scope) fixed = run_scope_fixed(ctx.run) + # K10:这次运行的类别、发起人与来源(发起时定下,恢复、接着跑沿用同一份)。caliber_query 按 run_class 选用途、 + # 用发起人当主体,并把来源带进派生的子运行;节点配置改不了这三样 + from app.engine.runner import RUN_OPTIONS_KEY + from app.tools.registry import RUN_CLASS_KEY, RUN_ORIGIN_KEY, RUN_STARTED_BY_KEY + return ToolContext( run_id=ctx.run.run_id, node_id=ctx.node.id, @@ -59,6 +113,10 @@ def _tool_ctx(ctx: NodeContext) -> ToolContext: catalog_view=catalog_view.of_run(ctx.run), # 数据源工具运行中途补固定版本时经它留一条事件(tools/datasource.py 的 _pin_late) emit=ctx.emit, + run_class=ctx.run.extra.get(RUN_CLASS_KEY), + started_by=ctx.run.extra.get(RUN_STARTED_BY_KEY), + run_options=dict(ctx.run.extra.get(RUN_OPTIONS_KEY) or {}), + origin=ctx.run.extra.get(RUN_ORIGIN_KEY), ) @@ -80,14 +138,28 @@ async def _dynamic_tool(name: str, ctx: NodeContext) -> Any: async def run_tool(state: GraphState, ctx: NodeContext) -> dict[str, Any]: - """直接调用一个工具。参数里的 {{ }} 会先用当前状态渲染。""" + """直接调用一个工具。参数里的 {{ }} 会先用当前状态渲染(写了一份参数契约的节点按契约渲染,见 _tool_args)。""" name = ctx.cfg("tool", "") if not name: raise NodeError(ctx.node.id, "「调用工具」节点尚未选择工具") - args = ctx.render(ctx.cfg("args", {}) or {}, state) + try: + args, material = _tool_args(ctx, state, name) + except ToolArgsError as e: + # 参数不完整(ledger/params):查询根本没发出去,按调用工具节点一贯的失败处理 + ctx.emit(EventType.TOOL_ERROR, tool=name, error=str(e)) + if ctx.cfg("fail_fast", True): + raise NodeError(ctx.node.id, str(e)) from e + return _arg_updates(ctx, str(e)) if not isinstance(args, dict): raise NodeError(ctx.node.id, "工具参数必须是 JSON 对象") + # K04:这个节点上的受控绑定材料(这条 SQL 是哪份绑定的哪一次展开)。核的是**节点配置里那条 SQL**(受控模板 + # 展开出来的那一条,{{ input.* }} 还在里面,归 K01),不是这一次渲染完的字面语句——值渲染进去之后就不再是 + # 模板展开的样子了。对不上就不写,不拿一份过时的绑定去解释实际执行过的语句 + from app.ledger import bindings as caliber_bindings + + binding_material = caliber_bindings.snapshot_material( + ctx.config or {}, (ctx.config or {}).get("args") if isinstance(ctx.config, dict) else None) # 能力治理后效果为写入的:走动作的路径(先留生效记录再发送,app/process/actions.py)。登记里没有、或不是写入的, # 照以前的路径执行 @@ -145,7 +217,14 @@ async def run_tool(state: GraphState, ctx: NodeContext) -> dict[str, Any]: async def _call() -> Any: async with SessionLocal() as session: - return await call_tool(name, args, _tool_ctx(ctx), session=session, on_fix=_fixed) + tool_ctx = _tool_ctx(ctx) + if material is not None: + # 参数材料进这一次调用的查询快照(tools/datasource._run):源模板、哈希、参数类型与写在哪儿 + tool_ctx.extra[sql_params.SNAPSHOT_KEY] = material + if binding_material is not None: + # K04 的绑定材料:这条 SQL 是哪份受控绑定的哪一次展开(业务值 + 绑定指纹) + tool_ctx.extra[caliber_bindings.SNAPSHOT_KEY] = binding_material + return await call_tool(name, args, tool_ctx, session=session, on_fix=_fixed) try: result = await run_bounded(_call(), limit, name) @@ -203,36 +282,56 @@ async def run_tool(state: GraphState, ctx: NodeContext) -> dict[str, Any]: ) except Exception: # noqa: BLE001 snapshot_id = None - # 只认平台执行的查询(数据源查询、登记里声明了 tabular 的端点读取,capabilities.registry.is_platform_query): - # 别的工具(MCP、自定义)拼出同样形状的 JSON,里面的工件 id 不是我们落的。按身份认,不看结果长得像不像(F11) - query = query_entry_fields(result) if evidence_on and is_platform_query(name) else None - # 端点读取另核一道(同 nodes/llm.py):名字对了,交回的工件还得是这次运行落下的端点快照。数据源查询的快照由数据层 - # 自己落,snapshot_owned 对它们直接放行 - if query and not await snapshot_owned(query["artifact"], ctx.run.run_id, name): - query = None - schema = query.get("schema_artifact") if query else None + # 只认平台执行的查询(数据源查询、K10 的口径查询 caliber_query、登记里声明了 tabular 的端点读取, + # capabilities.registry.is_platform_query):别的工具(MCP、自定义)拼出同样形状的 JSON,里面的工件 id 不是我们落 + # 的。按身份认,不看结果长得像不像(F11)。口径查询一次交回**多条**(queries 数组),这里逐条摊开、逐条认工件, + # 不把它当成只有一条。 + queries: list[dict[str, Any]] = [] + if evidence_on and is_platform_query(name): + for item in query_items(result, name): + artifact = str(item.get("artifact") or "") + # 端点读取、口径查询另核一道(同 nodes/llm.py):名字对了,交回的工件还得是这次运行(或它明确派生的子运行) + # 落下的那一种快照。数据源查询的快照由数据层自己落,snapshot_owned 对它们直接放行 + if artifact and await snapshot_owned(artifact, ctx.run.run_id, name): + queries.append(item) + first = queries[0] if queries else None + schema = first.get("schema_artifact") if first else None # 这次查询的 SQL 检查结果单独带上:preview 只有前 2000 个字符,checks 排在 rows 后面,通常被截掉 checks = event_checks(result) if is_platform_query(name) else [] ctx.emit(EventType.TOOL_END, tool=name, duration_ms=elapsed, preview=json.dumps(result, ensure_ascii=False, default=str)[:2000], - artifact=snapshot_id, **({"query_artifact": query["artifact"]} if query else {}), + artifact=snapshot_id, **({"query_artifact": first["artifact"]} if first else {}), + # 一次调用交回多条查询(caliber_query)时把工件 id 全列出来:只给第一条,界面上剩下的就点不开 + **({"query_artifacts": [q["artifact"] for q in queries]} if len(queries) > 1 else {}), **({"schema_artifact": schema} if schema else {}), **({"checks": checks} if checks else {})) updates: dict[str, Any] = {"nodes": {ctx.node.id: result}} if evidence_on: - # 证据台账:工具快照一条;查库的再记一条查询快照(外面包着的是工具快照)。报告按台账编 Q1… + # 证据台账:工具快照一条;查库的再逐条记查询快照(外面包着的是工具快照)。报告按台账编 Q1… exec_no = next_exec(state, ctx.node.id) entries: list[dict[str, Any]] = [] if snapshot_id: entries.append({"kind": "tool", "node_id": ctx.node.id, "exec": exec_no, "artifact": snapshot_id, "tool": name}) - if query: + for item in queries: + # 实际执行的执行身份(K10):query_id 是逻辑查询、execution_id 是这一次、attempt 是第几次。 + # 口径查询那条自己带着(K09 算好的),别的按这次节点执行的序号算 + identity = {"query_id": item.get("query_id") or ctx.node.id, + "execution_id": item.get("execution_id") or execution_id_of(ctx.node.id, attempt=exec_no, + run_id=ctx.run.run_id), + "attempt": item.get("attempt") or exec_no} + item_schema = item.get("schema_artifact") # 查询当时的表结构快照另记一条 schema 条目;取不回来的话查询条目也不带它(不启用实体核对) - frozen = schema_ledger_entry(schema, node_id=ctx.node.id, exec_no=exec_no) if schema else None - entries.append({"kind": "query", "node_id": ctx.node.id, "exec": exec_no, "artifact": query["artifact"], - **({"via": snapshot_id} if snapshot_id else {}), "tool": name, "source": query["source"], - "columns": query["columns"], "rows": query["rows"], "truncated": query["truncated"], - **({"schema_artifact": schema, "tables": query["tables"]} if frozen else {})}) + frozen = schema_ledger_entry(item_schema, node_id=ctx.node.id, exec_no=exec_no) if item_schema else None + entries.append({"kind": "query", "node_id": ctx.node.id, "exec": exec_no, "artifact": item["artifact"], + **({"via": snapshot_id} if snapshot_id else {}), "tool": name, "source": item["source"], + "columns": item["columns"], "rows": item["rows"], "truncated": item["truncated"], + **identity, + # 口径查询那条记下它在哪一版、哪张图、哪个取数节点:数据源查询没有这一项 + **({"origin": dict(item["origin"])} if item.get("origin") else {}), + # 复算要的材料(口径查询那条带着):这次参数输入的哈希与源模板的哈希,值本身不进台账 + **({"parameters": dict(item["parameters"])} if item.get("parameters") else {}), + **({"schema_artifact": item_schema, "tables": item.get("tables")} if frozen else {})}) if frozen: entries.append(frozen) if entries: @@ -355,6 +454,11 @@ def _write_updates(ctx: NodeContext, result: dict[str, Any]) -> dict[str, Any]: return updates +def _arg_updates(ctx: NodeContext, reason: str) -> dict[str, Any]: + """参数不完整、没发查询时的节点产出:原因交给下游(fail_fast=False 的节点照旧往下走)。不落查询快照——没有查询。""" + return _write_updates(ctx, {"error": reason}) + + def _query_failure(name: str, result: str) -> str: """调用工具节点上查询没查成时的报错。 diff --git a/backend/app/engine/origin.py b/backend/app/engine/origin.py index ffb8fa17..0545e0de 100644 --- a/backend/app/engine/origin.py +++ b/backend/app/engine/origin.py @@ -32,6 +32,12 @@ ORIGIN_KINDS = ( "caliber_trial", # 口径目录里的试跑(探索运行,不是问数回答,也不进统计/召回) ) +#: 进程内 QueryCore 固定执行(K09,app/ledger/querycore.py)用的来源:**沿用口径试跑这一档**——同样是「按一份固定口径跑 +#: 一次取数」的探索运行,不是有人在问数,也不进使用统计与召回比对。这一档的枚举与前端联合类型逐字对齐 +#: (tests/test_frontend_type_unions.py 比对 ORIGIN_KINDS),加一种新来源要同时改前端和 apps/resolve 的分类,这一轮不动它; +#: QueryCore 自己那几件事(版本、清单、闭包身份、用途、trace)记在 origin 数据的 service/purpose/… 上,不新开一档。 +QUERYCORE_ORIGIN = "caliber_trial" + #: 客户端在 POST /api/runs 里能声明的来源 CLIENT_ORIGINS = ("chat", "canvas", "launcher", "api") diff --git a/backend/app/engine/runner.py b/backend/app/engine/runner.py index 3688318a..bfd012c3 100644 --- a/backend/app/engine/runner.py +++ b/backend/app/engine/runner.py @@ -30,8 +30,9 @@ from app.engine.deadline import segment from app.engine.replay import PROTOCOL, PROTOCOL_KEY, protocol_of from app.engine.schema import GraphSpec, NodeType, loop_steps, topology_of, validate_graph from app.process.actions import ActionPending -from app.records.views import scope_entries +from app.records.views import inherit_scope, scope_entries from app.tools.datasource import RUN_VERSIONS_KEY +from app.tools.registry import RUN_CLASS_KEY, RUN_ORIGIN_KEY, RUN_STARTED_BY_KEY logger = logging.getLogger(__name__) @@ -289,6 +290,7 @@ class RunManager: started_by: str | None = None, approval_default: str | None = None, options: dict[str, Any] | None = None, + data_versions: dict[str, Any] | None = None, schedule_id: str | None = None, notes: Sequence[tuple[EventType | str, str | None, dict[str, Any]]] = (), origin_kind: str | None = None, @@ -300,6 +302,9 @@ class RunManager: origin_kind / origin / app_id / app_version 是运行来源(engine/origin.py),由 launch_run 定下,原样记在运行上; 对应的 run.origin 事件由 launch_run 放进 notes。 + data_versions 给定时照它固定这一次运行的上传表格版本,不再读数据源的当前指针:K10 派生的子运行照父 Run 那一份 + 固定(运行中途有人重传,父子两段查的仍是同一版)。不给照旧按图里用到的源现读当前指针。 + notes 是发起时就定下的事件 (类型, node_id, 数据),比如正式运行按什么级别出具、口径升版怎么处置。它们和 运行记录同一个事务提交,排在 run.started 前面:写不进去就不建运行,不会出现运行已经在执行、调用方却 只拿到一个异常(定时任务会把它记成未能发起);也不会和执行抢先后,运行结束得快时落到封存之后。 @@ -325,9 +330,16 @@ class RunManager: # 读上传表格的当前指针到运行记录提交,持着版本存储的锁:中间有人重传的话,发布后的回收 # 看不到这条还没提交的运行,会把刚固定的快照删掉(table_versions.pin_lock) async with pin_lock(): - data_versions = await _data_versions(session, spec) - # 记录表这次运行看哪些行:正式运行看全部,别的按发起人的授权(records/views.scope_entries) - await scope_entries(session, data_versions, run_class=run_class, started_by=started_by) + if data_versions is not None: + # 调用方(K10 派生的子运行)给了固定的数据版本:照它,不再读当前指针,父子两段查同一版; + # 记录表的行级范围也照父 Run 已授权的那一份**原样带着**,不在这里重算——子运行的类别是 + # exploratory,重算会把正式父 Run 的 all 收成 mine/none(views.inherit_scope) + pinned_versions = copy.deepcopy(data_versions) + inherit_scope(pinned_versions) + else: + pinned_versions = await _data_versions(session, spec) + # 记录表这次运行看哪些行:正式运行看全部,别的按发起人的授权(records/views.scope_entries) + await scope_entries(session, pinned_versions, run_class=run_class, started_by=started_by) run = Run( workflow_id=workflow_id, workflow_name=workflow_name, @@ -343,7 +355,7 @@ class RunManager: approval_default=approval_default, tool_trust=tool_trust, agent_limits=agent_limits, - data_versions=data_versions, + data_versions=pinned_versions, options=options, schedule_id=schedule_id, origin_kind=origin_kind, @@ -377,9 +389,12 @@ class RunManager: approval_default=approval_default, tool_trust=tool_trust, agent_limits=agent_limits, - data_versions=data_versions, + data_versions=pinned_versions, options=options, origin_kind=origin_kind, + run_class=run_class, + started_by=started_by, + origin=origin, ) ) return run @@ -777,6 +792,9 @@ class RunManager: resumed: list[str] | tuple[str, ...] = (), actors: dict[str, str | None] | None = None, origin_kind: str | None = None, + run_class: str = "exploratory", + started_by: str | None = None, + origin: dict[str, Any] | None = None, ) -> None: from app.cluster import slots @@ -809,11 +827,15 @@ class RunManager: fenced = False # 先要并发名额(app/cluster/slots.py)。等名额的时候被停止(或者关停)也要照实收尾,见 _stopped_in_queue slot = slots.hold(run_id, origin_kind) + # K13:这次要并发名额用了多久(毫秒)——要名额前后各量一次。这一段在各段 started_at 之前,既不算 active 也不算 + # wall,单独记在运行记录的 usage.queue_ms 上;它和等人审批的 wait_ms 是两回事,谁也不冒充谁 + queued_at = time.perf_counter() try: await slot.__aenter__() except asyncio.CancelledError: - await self._stopped_in_queue(run_id) + await self._stopped_in_queue(run_id, queue_ms=_elapsed_ms(queued_at)) raise + queue_ms = _elapsed_ms(queued_at) try: # 执行时长从拿到名额算起:排队等名额的那一段不算执行(墙钟从 started_at 算,started_at 也是拿到名额之后才写) started = time.perf_counter() @@ -869,7 +891,12 @@ class RunManager: extra={"resumed": set(resumed), "actors": dict(actors or {}), RUN_VERSIONS_KEY: dict(data_versions) if data_versions is not None else None, # 同理也是一份拷贝:节点读它,不该改到运行记录那份 - RUN_OPTIONS_KEY: copy.deepcopy(options or {})}, + RUN_OPTIONS_KEY: copy.deepcopy(options or {}), + # K10:这次运行的类别、发起人与来源。构造 ToolContext 的节点把它们交给工具——caliber_query + # 按 run_class 选用途(formal 走 formal judge)、拿发起人当主体,并把来源带进派生的子运行 + RUN_CLASS_KEY: run_class, + RUN_STARTED_BY_KEY: started_by, + RUN_ORIGIN_KEY: copy.deepcopy(origin) if origin else None}, ) app = compile_graph(spec, run_ctx).compile(checkpointer=self.checkpointer) # 循环按自己声明的轮数另记一份预算,全局上限只管没人把关的环 @@ -980,7 +1007,8 @@ class RunManager: try: if not fenced: await self._finalize(run_id, status, error, final_state, elapsed, terminal=terminal, - error_node=error_node, end_reason=end_reason, owner=mine) + error_node=error_node, end_reason=end_reason, owner=mine, + queue_ms=queue_ms) # 记 action.unknown、安排核实也算收尾:做完才把自己摘掉。以前摘掉之后才做,等运行「不在跑了」 # 再去读事件的一方(接口、测试)有一小段读不到这一条;库慢一点(PostgreSQL 满载时)就读不到 if pending_action is not None and not fenced: @@ -1048,9 +1076,11 @@ class RunManager: self._tasks.pop(run_id, None) self._stopped_by.pop(run_id, None) - async def _stopped_in_queue(self, run_id: str) -> None: + async def _stopped_in_queue(self, run_id: str, *, queue_ms: int = 0) -> None: """还在等并发名额时被取消。关停:什么都不写(还是排队中 / 刚认领的样子),照「属主不在了」的规矩由下次启动或别的 - 进程接手(排队的标失败、认领了的标中断);人点了停止:收成 cancelled,同执行中停止(run.cancelled 带上是谁停的、封存)。""" + 进程接手(排队的标失败、认领了的标中断);人点了停止:收成 cancelled,同执行中停止(run.cancelled 带上是谁停的、封存)。 + + queue_ms 是这次等到被叫停时已经排了多久(毫秒):照实记下来,不丢那一段。""" try: if self._closing: return @@ -1058,7 +1088,7 @@ class RunManager: return actor = self._stopped_by.pop(run_id, None) self._finalizing.add(run_id) - await self._finalize(run_id, "cancelled", "用户取消", {}, 0, + await self._finalize(run_id, "cancelled", "用户取消", {}, 0, queue_ms=queue_ms, terminal=(EventType.RUN_CANCELLED, {"reason": END_STOPPED, "actor": actor}), end_reason=END_STOPPED, owner=identity.owner()) finally: @@ -1148,12 +1178,16 @@ class RunManager: error_node: str | None = None, end_reason: str | None = None, owner: str | None = None, + queue_ms: int = 0, ) -> None: - """收尾。owner:执行这一段的属主——运行那一行的属主已经不是它(被别的进程当成没了接手了,cluster/fence.py)就什么都不写。""" + """收尾。owner:执行这一段的属主——运行那一行的属主已经不是它(被别的进程当成没了接手了,cluster/fence.py)就什么都不写。 + + queue_ms:这一段等并发名额等了多久(K13,见 _drive)。它不进 active/wall(那两样从拿到名额之后算起),单独累加成 + usage.queue_ms 随终态事件一起发出。""" usage = dict(state.get("usage") or {}) output = dict(state.get("output") or {}) now = datetime.now(timezone.utc) - timing = {"wall_ms": elapsed_ms, "active_ms": elapsed_ms, "wait_ms": 0} + timing = {"wall_ms": elapsed_ms, "active_ms": elapsed_ms, "wait_ms": 0, "queue_ms": max(0, int(queue_ms))} # 终态事件和运行记录在同一个事务里提交,提交之后再广播。两边都有人在读: # 读到 failed 的一方马上去翻事件,要翻得到 run.failed(报错原因和定位都在 @@ -1177,7 +1211,7 @@ class RunManager: if run: app_id = run.app_id run_class, origin_kind = run.run_class, run.origin_kind - timing = await _timing(session, run, elapsed_ms, now) + timing = await _timing(session, run, elapsed_ms, now, queue_ms=queue_ms) events_usage = await _usage_of_events(session, run_id) inquiry = events_usage.pop("inquiry", None) if status != "succeeded": @@ -1410,6 +1444,10 @@ def _carried(run: Run) -> dict[str, Any]: "options": run.options or {}, # 并发名额按来源归类(app/cluster/slots.py):恢复、接着跑的那一段和第一段同一类 "origin_kind": run.origin_kind, + # K10:类别、发起人与来源照运行记录来——恢复、接着跑的那一段里,caliber_query 仍按同一个用途、同一个主体执行 + "run_class": run.run_class or "exploratory", + "started_by": run.started_by, + "origin": run.origin if isinstance(run.origin, dict) else None, } @@ -1432,11 +1470,15 @@ async def _data_versions(session: Any, spec: GraphSpec) -> dict[str, Any]: 记录表(origin=records,docs/design/normal-user-apps.md N8)同样在这里固定高水位:{"seq": 高水位, …} (records/views.pin_entry)。这次运行看哪些行由发起处另外记上(records/views.scope_entries):按需视图的缓存键 只要高水位。 + + 经某个口径(caliber_query 节点点名的那些)固定到的源,项上另记一条 `caliber` = 那份口径的固定目标 + (querycore.target_key):之后同一次运行里换了另一份口径目标、而这个源又换过版本时,那一层要照实说冲突 + (querycore.pin_sources_for_parent),不能悄悄读另一版。 """ from app.db.models import DataSource from app.records.views import pin_entry - names, anything = await _bound_sources(session, spec) + names, anything, calibers = await _bound_sources(session, spec) if not names and not anything: return {} query = select(DataSource.id, DataSource.name, DataSource.current_snapshot_id).where( @@ -1454,33 +1496,53 @@ async def _data_versions(session: Any, spec: GraphSpec) -> dict[str, Any]: for source in (await session.execute(records)).scalars(): if (entry := await pin_entry(session, source)) is not None: out[source.id] = entry + for entry in out.values(): + if key := calibers.get(str(entry.get("name") or "")): + entry["caliber"] = key return out -async def _bound_sources(session: Any, spec: GraphSpec) -> tuple[set[str], bool]: - """图里(含子工作流)绑定的数据源工具指向的源名,以及有没有带模板、发起时定不下来的工具名。 +async def _bound_sources(session: Any, spec: GraphSpec) -> tuple[set[str], bool, dict[str, str]]: + """图里(含子工作流)绑定的数据源工具指向的源名、有没有带模板、发起时定不下来的工具名,以及**经口径固定**的 + 源名 → 那份口径的固定目标(`caliber` 标记,只给没有直接绑定的源)。 绑定的取法和发起前检查同一个(engine/launch.py 的 tool_bindings),子工作流照运行时的取法 读出来接着找:固定了版本的读那一版,没固定的读工作流现在的图。读不到、图不成形的跳过—— 那个节点运行时自己会报错。同一个工作流(同一版)只读一次,互相引用也不会转圈。 + + K10 还要多算一样:绑了 `caliber_query` 的节点,它真正读的取数节点**不在本图里**,在它点名的口径那一版图里 + (`_caliber_sources`)。不在这里先固定,父 Run 的两次调用会各自在派生的子运行里补固定(pin_late),中间有人 + 重传就会一次运行里读两版数据。 """ # 在函数里导入:launch 在模块级导入了本模块(它要 run_manager) from app.engine.launch import node_setting, tool_bindings from app.db.models import WorkflowVersion + from app.ledger.querycore import CALIBER_QUERY from app.tools.datasource import source_of_tool names: set[str] = set() + direct: set[str] = set() anything = False seen: set[tuple[str, str]] = set() + calibers: dict[str, str] = {} + seen_calibers: set[tuple[str, str]] = set() queue: list[GraphSpec] = [spec] while queue: graph = queue.pop(0) for _, tool in tool_bindings(graph): + if tool == CALIBER_QUERY: + continue # 它的源按节点的参数另认(工具名列表里读不出 workflow / card) if "{{" in tool: anything = True elif (source := source_of_tool(tool)) is not None: names.add(source) + direct.add(source) for node in graph.nodes: + if _binds_caliber(graph, node): + found, unsure = await _caliber_sources(session, graph, node, seen_calibers) + names |= set(found) + calibers.update(found) + anything = anything or unsure if node.type != NodeType.SUBGRAPH: continue # 和 NodeContext.cfg 一样:节点上没写就取图级 defaults(tool_bindings 读工具也是这个规则) @@ -1499,7 +1561,70 @@ async def _bound_sources(session: Any, spec: GraphSpec) -> tuple[set[str], bool] queue.append(GraphSpec.model_validate(sub)) except Exception: # noqa: BLE001 - 读不到、不成形:子工作流节点运行时会说清楚 continue - return names, anything + # 图里自己直接绑了这个源的:不记口径标记——那份固定首先是为这张图要的,不是为某一份口径 + return names, anything, {name: key for name, key in calibers.items() if name not in direct} + + +def _binds_caliber(spec: GraphSpec, node: Any) -> bool: + """这个节点绑没绑口径查询工具(调用工具节点、Agent、协作成员的成员,取值规则同 tool_bindings)。""" + from app.engine.launch import node_setting + from app.ledger.querycore import CALIBER_QUERY + + if node.type == NodeType.TOOL: + return node_setting(spec, node, "tool") == CALIBER_QUERY + if node.type == NodeType.AGENT: + return CALIBER_QUERY in [n for n in node_setting(spec, node, "tools") or [] if isinstance(n, str)] + if node.type == NodeType.SUPERVISOR: + return any(CALIBER_QUERY in [n for n in (member.get("tools") or []) if isinstance(n, str)] + for member in node_setting(spec, node, "agents") or [] if isinstance(member, dict)) + return False + + +async def _caliber_sources(session: Any, spec: GraphSpec, node: Any, + seen: set[tuple[str, str]]) -> tuple[dict[str, str], bool]: + """绑了 `caliber_query` 的节点会读到哪些源、以及这些源是为**哪一份口径目标**固定的(K10)。 + + 按它点名的口径**那一版**(推荐版)图里的取数节点认(`querycore.card_sources`)。发起时就把它们固定进父 Run 的 + data_versions:父 Run 的同一次运行里两次调用口径查询,读的还是同一版数据,中间有人重传也不会让后一次读到新的 + 一版;项上另记 `caliber` = 这份目标(`querycore.target_key`),之后换了另一份目标、源又换过版本时那一层会 + 照实说冲突。 + + 定不下来的一律返回「说不准」(anything=True,发起时把启用的上传源、记录表全部固定上):口径是 Agent 挑的 + (工具名在参数里,模型运行时才写)、workflow / card 写的是模板、图不成形——多固定几个只是多留几个旧版本, + 漏一个就会让同一次运行前后两段查到两版数据。认得到工作流但还没有推荐版、认不到工作流或卡时返回 False:那种 + 调用会在 QueryCore 那一层被拒(没有发布版 / 清单核不过),一条数据都不会读,不必把全部源都固定上。""" + from app.apps import publications + from app.db.models import Workflow + from app.engine.launch import node_setting + from app.ledger.querycore import card_sources, target_key + + if node.type != NodeType.TOOL: + # Agent / 协作成员:workflow、card、metric_ids 都是模型在这一轮里挑的,发起时说不出它会读哪个源 + return {}, True + raw = node_setting(spec, node, "args") + args = raw if isinstance(raw, dict) else {} + ref, card = str(args.get("workflow") or "").strip(), str(args.get("card") or "").strip() + if not ref or not card or "{{" in ref or "{{" in card: + return {}, True + key = (ref, card) + if key in seen: + return {}, False + seen.add(key) + workflow = await session.get(Workflow, ref) + if workflow is None: + rows = list((await session.execute(select(Workflow).where(Workflow.name == ref))).scalars()) + if len(rows) != 1: + return {}, False # 认不到:这一次调用会被 QueryCore 拒(找不到工作流) + workflow = rows[0] + row = await publications.recommended(session, workflow) + if row is None: + return {}, False # 还没有推荐版:这一次调用会被拒(没有可执行的发布版) + graph = row.graph if isinstance(row.graph, dict) else None + if not graph: + return {}, True # 这一版图读不出来:说不准它读什么,按最保守的处置 + names, _sure = card_sources(graph, card) + pinned_for = target_key(workflow.id, row.version, card) + return {name: pinned_for for name in names}, False async def _agent_limits(session: Any) -> dict[str, Any]: @@ -1799,15 +1924,26 @@ def _spent(state_usage: dict[str, Any], events_usage: dict[str, Any]) -> dict[st return out -async def _timing(session: Any, run: Run, elapsed_ms: int, now: datetime) -> dict[str, int]: - """wall:从第一次开始到现在的墙钟;active:各段执行时长之和;wait:等人审批的总时长。 +def _elapsed_ms(since: float) -> int: + """从 perf_counter 的那一刻到现在过了多少毫秒(K13 的排队计时用)。""" + return max(0, int((time.perf_counter() - since) * 1000)) + + +async def _timing(session: Any, run: Run, elapsed_ms: int, now: datetime, queue_ms: int = 0) -> dict[str, int]: + """wall:从第一次开始到现在的墙钟;active:各段执行时长之和;wait:等人审批的总时长; + queue:从要并发名额到拿到名额的总时长(K13)。 等待按事件算:每段从 run.interrupted 到下一条 run.resumed。服务重启挂起的那段 没有 run.interrupted,不算等审批;失败后到接着跑之间也不算。 + + queue 是各段**拿到名额之前**那一下(_drive 量的:等别人放名额 + 发名额那一下的开销)之和:那一截在 started_at + 之前,既不在 wall 里也不在 active 里,所以单独记。它和 wait(等人)是两回事,互相不冒充;加这一项之前跑完的 + 老运行没有这个键。 """ prev = run.usage or {} before = prev.get("active_ms", prev.get("duration_ms", 0)) active = int(before or 0) + elapsed_ms + queued = int(prev.get("queue_ms") or 0) + max(0, int(queue_ms or 0)) rows = await session.execute( select(RunEvent.type, RunEvent.ts) @@ -1826,7 +1962,8 @@ async def _timing(session: Any, run: Run, elapsed_ms: int, now: datetime) -> dic waited += max(0.0, now.timestamp() - since) wall = int((now - run.started_at).total_seconds() * 1000) if run.started_at else active - return {"wall_ms": max(wall, active), "active_ms": active, "wait_ms": int(waited * 1000)} + return {"wall_ms": max(wall, active), "active_ms": active, "wait_ms": int(waited * 1000), + "queue_ms": queued} run_manager = RunManager() diff --git a/backend/app/engine/schema.py b/backend/app/engine/schema.py index b789ffa8..a20dbcdb 100644 --- a/backend/app/engine/schema.py +++ b/backend/app/engine/schema.py @@ -540,7 +540,11 @@ def _check_dual_check(node: GraphNode, spec: GraphSpec, result: ValidationResult "请把口径卡连到双盲复算之前", "card", "dual_check.card_invalid") return if target.config.get("caliber_from") not in (None, "", {}): - known = None + # 转抄卡:钉住那一版的指标清单不在本图里。带了指标选择(caliber_from.metrics,K08)时,这张卡这次只会算出选中的 + # 那些——可选的指标清单就是它,按它校验;没带选择才认不出(照旧不查指标 ID) + ref = target.config.get("caliber_from") + selection = ref.get("metrics") if isinstance(ref, dict) else None + known = [str(m) for m in selection] if isinstance(selection, list) and selection else None else: known = [str(d.get("id")) for d in target.config.get("metrics") or [] if isinstance(d, dict) and d.get("id")] hint = (",可选的指标 ID:" + "、".join(known[:12])) if known else "" @@ -1370,6 +1374,14 @@ def validate_graph(spec: GraphSpec) -> ValidationResult: for issue in metric_definition_issues(node, d, i): result.add(issue.message, level=issue.level, node_id=issue.node_id, field=issue.field, code=issue.code) + # K08:同一张卡上的指标 ID 要唯一。下游按 ID 与位置取数(nodes.<卡>.metrics[i]、出具契约、比例契约), + # 重复了分不清是哪一条——画布 / 发布前检查就拦住,别等到运行时把第一条静默算出来 + from app.engine.nodes.metrics import duplicate_metric_ids + + for duplicated in duplicate_metric_ids(defs): + result.add(f"指标 ID「{duplicated}」在这张口径卡上重复了:同一张卡上的指标 ID 要唯一(下游按 ID 与位置" + f"取数,重复了分不清是哪一条)", node_id=node.id, field="metrics", + code="metrics.id_duplicate") elif node.type == NodeType.DUAL_CHECK: _check_dual_check(node, spec, result) elif node.type == NodeType.REPORT: @@ -2028,6 +2040,16 @@ def _caliber_from_issues(node: GraphNode, policies: set[str], labels: dict[str, elif new not in upstream: add(f"「{field_label('caliber_from')}」改名后的取数节点「{nodes[new].title}」不在口径卡的上游:口径卡计算时" "它还没有执行。请把它连到口径卡之前", "caliber_from.nodes") + # K08:可选指标选择(caliber_from.metrics)。这里只看形状——钉住那一版的指标清单不在本图里,具体有没有这个指标 + # 由运行时按那一版判(未知、空的选择运行时响亮失败,绝不退回整卡) + selection = ref.get("metrics") + if selection is not None: + if isinstance(selection, (str, bytes)) or not isinstance(selection, list) \ + or any(not isinstance(m, str) or not m.strip() for m in selection): + add(f"「{field_label('caliber_from')}」的指标选择(metrics)要写成一串指标 id", "caliber_from.metrics") + elif not selection: + add(f"「{field_label('caliber_from')}」的指标选择(metrics)是空的:一个指标也不选。不写表示按整卡算," + "要选就点名要算的指标", "caliber_from.metrics") if cfg.get("metrics"): add(f"已设置「{field_label('caliber_from')}」,将按所引用的口径卡计算,此处填写的「{field_label('metrics')}」" "不会生效", "metrics", level="warning") diff --git a/backend/app/engine/variables.py b/backend/app/engine/variables.py index 8761faad..40638593 100644 --- a/backend/app/engine/variables.py +++ b/backend/app/engine/variables.py @@ -11,6 +11,10 @@ - **引用早于产出** —— 变量确实存在,但那个节点在它之后才跑,这时候取到的是空 - **产出了没人用** —— 不一定是错,但常常是改图改了一半的残留 +例外只有一种:带参数契约的节点(ledger/params 的 marker,组合式问数拷进来的取数节点、对账图里服务器拼的对齐语句), +它的 args / sql 是服务端已经渲染好的**字面**语句——里面的 `{{ }}` 是数据,不按变量引用判(见 _live_strings)。这条例外 +要**核对过契约里的哈希**才算:节点被复制、args / sql 改过之后契约作废,改过的内容照常扫。 + 顺带把"这张图里到底有哪些变量"列出来,界面上的变量表和输入补全都用它。 """ @@ -181,6 +185,21 @@ def _iter_strings(value: Any, prefix: str = "") -> list[tuple[str, str]]: return out +def _live_strings(cfg: dict[str, Any], node_type: str) -> list[tuple[str, str]]: + """节点配置里**还该当活模板看**的字符串:带参数契约的节点(ledger/params 的 marker),args / sql 是服务端已经按参数 + 渲染好的字面语句,里面的 {{ }} 是数据(取数结果、维度值),不是变量引用——跳过那几个键。 + + 只有契约里的 rendered_hash 与当前那一项对得上才跳(见 params.literal_keys):节点被复制、args / sql 改过之后契约作废, + 改过的内容照常全扫——那时它是作者写的模板,写错了仍然要在跑之前说破。 + + 别的节点、别的键照旧全扫:正常模板写错了({{ vars.quesiton }})仍然要在跑之前说破。""" + from app.ledger import params + + rendered = params.literal_keys(cfg, node_type) + live = {k: v for k, v in cfg.items() if k not in rendered} if rendered else cfg + return _iter_strings(live) + + def _root_of(expr: str) -> tuple[str, str]: """把 `vars.sales | json` 拆成 ('vars.sales', 'vars')。模板函数(`file_text(input.附件, 8000)`)按它的第一个 参数认:引用的是 input.附件。""" @@ -376,7 +395,7 @@ def analyze(spec: GraphSpec) -> VariableReport: target.refs.append(VarRef(node_id=node.id, node_label=label, field=f"inputs.{alias}", expr=f"nodes.{source}")) - for field, text in _iter_strings(cfg): + for field, text in _live_strings(cfg, str(node.type)): for m in _TEMPLATE_RE.finditer(text): expr = m.group(1).strip() if not expr: diff --git a/backend/app/engine/verify_agent.py b/backend/app/engine/verify_agent.py index f44d5c03..0d2deb12 100644 --- a/backend/app/engine/verify_agent.py +++ b/backend/app/engine/verify_agent.py @@ -63,12 +63,13 @@ from typing import Any from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage, ToolMessage +from app.capabilities.registry import is_platform_query, query_items, snapshot_owned from app.core import artifact_store from app.core.errors import describe_exception, not_configured from app.core.events import EventType from app.db.base import SessionLocal from app.engine import spend -from app.engine.evidence import build_catalog, cell_eid, compose_doc, query_entry_fields, schema_ledger_entry +from app.engine.evidence import build_catalog, cell_eid, compose_doc, schema_ledger_entry from app.engine.expressions import CellError, column_kind, locate_cell, numeric_text from app.engine.judge import FALLBACK_MAX_TOKENS, MAX_TOKENS, _json_in, _tokens, _usd from app.engine.masking import SeenValues, _masked_word, _Secrets @@ -79,7 +80,7 @@ from app.providers import catalog as pricing from app.providers.budget import BudgetFallback, budget_refused, cut_off, cut_words, error_usage, truncated_error from app.providers.factory import ModelSpec, ProviderNotConfigured, bind_tools_safely, get_chat_model from app.tools.datasource import MASKED_VALUES_KEY, QUERY_PREFIX, SCHEMA_PREFIX, build_datasource_tools -from app.tools.registry import ToolArgsError, ToolContext, Versions, args_model_of, prepare_args +from app.tools.registry import ToolArgsError, ToolContext, Versions, args_model_of, execution_id_of, prepare_args logger = logging.getLogger(__name__) @@ -960,7 +961,10 @@ async def _verify(state: _State, *, spec: ModelSpec, system: str, task: str, sou await _announce(emit, EventType.TOOL_ERROR, tool=name, call_id=call_id, error=str(e), role="verify") messages.append(ToolMessage(content=str(e), tool_call_id=call_id)) continue - is_query = name.startswith(QUERY_PREFIX) + # 平台执行的查询都算「一次查询」:数据源查询、K10 的口径查询(caliber_query,一次交回多条 SQL)都一样按 + # 调用次数记账。按身份认(is_platform_query),不看结果长得像不像;db_query、db_schema 这些能绑进来的 + # 工具判出来和按前缀认完全一样,旧行为不变 + is_query = is_platform_query(name) fingerprint = f"{name}\n{json.dumps(args, ensure_ascii=False, sort_keys=True, default=str)}" if is_query and fingerprint in done: alias = done[fingerprint] @@ -977,14 +981,18 @@ async def _verify(state: _State, *, spec: ModelSpec, system: str, task: str, sou stopped = "timeout_s" messages.append(ToolMessage(content="未执行:已达核查的时长上限,不能再查询。", tool_call_id=call_id)) continue - content = await _run_tool(tool, name, args, call_id, remaining, emit, queries, ledger, owner) + before = len(queries) + content = await _run_tool(tool, name, args, call_id, remaining, emit, queries, ledger, owner, + run_id=run_id) if content is None: stopped = "timeout_s" content = "查询因核查的时长上限被中断,没有结果。" if is_query: attempts += 1 - if queries and queries[-1]["call_id"] == call_id: - done[fingerprint] = queries[-1]["alias"] + # 一模一样的不再执行(done 按工具名 + 参数认)。一次调用交回多条查询(口径查询)时记的是**第一条** + # 的编号:交回模型的那句「结果见 Qn」点的是它 + if len(queries) > before: + done[fingerprint] = queries[before]["alias"] messages.append(ToolMessage(content=content, tool_call_id=call_id)) if not stopped and max_queries is not None and attempts >= max_queries: stopped = "max_queries" @@ -1112,13 +1120,29 @@ def _with_fallback(model: Any, spec: ModelSpec, small: int | None, model_id: str key=(spec.provider, model_id, spec.max_tokens)) +async def _owned_queries(content: str, name: str, *, run_id: str) -> list[dict[str, Any]]: + """这次工具调用交回、**可以作证**的查询条目:按身份摊开(capabilities.registry.query_items——数据源查询一条、 + K10 的口径查询是 queries 数组里**多条**),逐条认工件(snapshot_owned——口径查询那条必须是这次运行或它明确派生的 + 子运行落下的查询快照,伪造的、别的运行落的、别的种类的一律不要)。不是平台执行的查询返回空:拼一份同样形状的 + JSON 不算证据。抽取和认工件与 Agent 节点、调用工具节点是同一份,不另写一套按结果长相猜的逻辑。""" + if not is_platform_query(name): + return [] + out: list[dict[str, Any]] = [] + for item in query_items(content, name): + artifact = str(item.get("artifact") or "") + if artifact and await snapshot_owned(artifact, run_id, name): + out.append(item) + return out + + async def _run_tool(tool: Any, name: str, args: dict[str, Any], call_id: str, remaining: float | None, emit: Emit | None, queries: list[dict[str, Any]], ledger: list[dict[str, Any]], - owner: str) -> str | None: + owner: str, run_id: str = "") -> str | None: """执行一次工具调用,返回交给模型的内容;整个核查的时长到点、这次被中断时返回 None。 - 成功的查询编号(Q1、Q2…)、记进本 agent 自己的台账和查询清单,内容前面加「【证据 Qn】」。 - """ + 成功的查询编号(Q1、Q2…)、记进本 agent 自己的台账和查询清单,内容前面加「【证据 Qn】」。一次调用交回**多条**查询 + (K10 的口径查询,结果里是 queries 数组)时逐条编号、逐条记:抽取与认工件走和数据源查询同一份 + (capabilities.registry.query_items / snapshot_owned),不因为带的是数组就只认第一条。""" limit = limit_of(tool, name, args) await _announce(emit, EventType.TOOL_START, tool=name, args=args, call_id=call_id, role="verify", **limit_fields(limit)) @@ -1143,28 +1167,44 @@ async def _run_tool(tool: Any, name: str, args: dict[str, Any], call_id: str, re duration_ms=int((time.perf_counter() - began) * 1000), error=message[:300]) return message elapsed = int((time.perf_counter() - began) * 1000) - fields = query_entry_fields(content) if name.startswith(QUERY_PREFIX) else None + items = await _owned_queries(content, name, run_id=run_id) extra: dict[str, Any] = {} - if fields is not None: - alias = f"Q{len(queries) + 1}" + if items: data = json.loads(content) - schema = fields.get("schema_artifact") - seen = schema and any(e.get("kind") == "schema" and e.get("artifact") == schema for e in ledger) - frozen = schema_ledger_entry(schema, node_id=owner, exec_no=1) if schema and not seen else None - shaped = {"schema_artifact": schema, "tables": fields["tables"]} if seen or frozen else {} - ledger.append({"kind": "query", "node_id": owner, "exec": 1, "artifact": fields["artifact"], - "call_id": call_id, "tool": name, "source": fields["source"], "columns": fields["columns"], - "rows": fields["rows"], "truncated": fields["truncated"], **shaped}) - if frozen: - ledger.append(frozen) - queries.append({"alias": alias, "call_id": call_id, "tool": name, "source": fields["source"], - "sql": str(data.get("sql") or args.get("sql") or ""), "artifact": fields["artifact"], - "columns": fields["columns"], "rows": data.get("rows") or [], "row_count": fields["rows"], - "truncated": fields["truncated"]}) - extra = {"query_artifact": fields["artifact"], "alias": alias, - **({"schema_artifact": schema} if schema else {}), + aliases: list[str] = [] + artifacts: list[str] = [] + for item in items: + alias = f"Q{len(queries) + 1}" + aliases.append(alias) + artifact = str(item["artifact"]) + artifacts.append(artifact) + schema = item.get("schema_artifact") + seen = schema and any(e.get("kind") == "schema" and e.get("artifact") == schema for e in ledger) + frozen = schema_ledger_entry(schema, node_id=owner, exec_no=1) if schema and not seen else None + shaped = {"schema_artifact": schema, "tables": item["tables"]} if seen or frozen else {} + # 实际执行的执行身份(K10):query_id 是逻辑查询、execution_id 是这一次、attempt 是第几次。口径查询那条 + # 自己带着(K09 算好的),别的按这次调用的 id 算(同 Agent 节点、调用工具节点) + identity = {"query_id": item.get("query_id") or owner, + "execution_id": item.get("execution_id") or execution_id_of(owner, attempt=1, + call_id=call_id, run_id=run_id), + "attempt": item.get("attempt") or 1} + ledger.append({"kind": "query", "node_id": owner, "exec": 1, "artifact": artifact, + "call_id": call_id, "tool": name, "source": item.get("source"), + "columns": item["columns"], "rows": item["rows"], "truncated": item["truncated"], + **identity, **shaped}) + if frozen: + ledger.append(frozen) + queries.append({"alias": alias, "call_id": call_id, "tool": name, "source": item.get("source"), + "sql": str(data.get("sql") or args.get("sql") or ""), "artifact": artifact, + "columns": item["columns"], + "rows": (data.get("rows") or []) if data.get("artifact") == artifact else [], + "row_count": item["rows"], "truncated": item["truncated"], **identity}) + first = items[0] + extra = {"query_artifact": artifacts[0], "alias": aliases[0], + **({"query_artifacts": artifacts} if len(artifacts) > 1 else {}), + **({"schema_artifact": first["schema_artifact"]} if first.get("schema_artifact") else {}), **({"checks": data["checks"]} if isinstance(data.get("checks"), list) and data["checks"] else {})} - content = f"【证据 {alias}】\n{content}" + content = f"【证据 {'、'.join(aliases)}】\n{content}" await _announce(emit, EventType.TOOL_END, tool=name, call_id=call_id, duration_ms=elapsed, preview=content[:2000], role="verify", **extra) if len(content) > _TOOL_CHARS: diff --git a/backend/app/ledger/authoring.py b/backend/app/ledger/authoring.py index dc1e75c9..e7d16524 100644 --- a/backend/app/ledger/authoring.py +++ b/backend/app/ledger/authoring.py @@ -5,6 +5,7 @@ import copy import logging import re from typing import Any +from uuid import uuid4 from sqlalchemy import select from sqlalchemy.ext.asyncio import AsyncSession from app.db.base import SessionLocal @@ -120,7 +121,7 @@ async def _schema_material(session: AsyncSession, source: DataSource, focus_text async def _published_metrics(session: AsyncSession) -> list[dict[str, Any]]: """已发布口径里的每一项指标,给 docdraft.alignment 用:{workflow_id, version, node_id, name, synonyms, unit, - definition_text}。直接复用 descriptor.list_calibers 的认法(只看最新已发布且未退役版本的源头口径卡)。""" + definition_text}。直接复用 descriptor.list_calibers 的认法(只看每个工作流推荐发布版里的源头口径卡,K07)。""" from app.ledger.descriptor import list_calibers out: list[dict[str, Any]] = [] @@ -212,13 +213,18 @@ def _fresh_metrics(metrics: list[dict[str, Any]], covered: list[str]) -> list[di def _draft_payload(*, entries: list[dict[str, Any]], blocks: list[dict[str, Any]], problems: list[dict[str, Any]], questions: list[str], uncovered: list[str], progress: dict[str, int], doc_truncated: bool, catalog_truncated: bool, model_id: str, - salvaged: bool) -> dict[str, Any]: - """草稿 payload 的形状:整份指标、各组 SQL、进度。起草中途也按它写回,页面靠 progress 显示第几轮、覆盖了几条。 + salvaged: bool, source_snapshot: dict[str, Any] | None = None, + prompts: list[dict[str, Any]] | None = None) -> dict[str, Any]: + """草稿 payload 的形状:整份指标、各组 SQL、进度、来源快照引用、提示记录。 + 起草中途也按它写回,页面靠 progress 显示第几轮、覆盖了几条。 blocks 是组数(不是内容);sql 把各组的取数拼在一起(组间空一行),人看的是「这次一共要跑哪几条」。groups 逐组给出 sql、入口字段和这一组的指标 id(与 metrics 里出现的顺序一致):页面按组画「这条 SQL 出哪几个指标」,不必再从拼接 出来的 sql 里猜边界。truncated 仍是 doc_truncated 与 catalog_truncated 的「或」,老前端只认这一个键。 + source_snapshot 是这次抽取读到的来源材料在工件库里的引用(原文在工件里,这里只记 id);prompts 记录每次模型提示 + 实际看到了哪几段。两样都不放进 checkpoint:checkpoint 只作任务恢复,来源基线与它无关(见 extract)。 + 所有路径(每轮落库、失败、出图)都经过这里,groups 只从同一份 blocks 生成,不另存一份状态。 """ return { @@ -242,12 +248,88 @@ def _draft_payload(*, entries: list[dict[str, Any]], blocks: list[dict[str, Any] "doc_truncated": doc_truncated, "catalog_truncated": catalog_truncated, "model_id": model_id, + "source_snapshot": source_snapshot, + "prompts": list(prompts or []), "open_questions": questions, "uncovered": uncovered, "salvaged": salvaged, } +async def _capture_source(*, documents: list[dict[str, Any]], chunks: dict[str, dict[str, Any]], + datasource: dict[str, Any], catalog: str, guidance: str, fixed_filters: str, + draft_id: str) -> dict[str, Any] | None: + """把这次抽取读到的来源材料存成一份不可变工件,返回草稿里要记的引用;落库失败返回 None。 + + 存的是**可还原的原文**(逐份、逐段)加上目录文本和补充要求,不是一串哈希——只有哈希还原不了 B。工件按内容寻址 + (app/core/artifact_store),同一份材料只存一份,读的时候还会复验哈希。落库失败不让整份草稿失败:草稿照出,但 + source_snapshot 为空(source_baseline 会照实说 baseline_unknown),不假装有基线。 + """ + from app.core.artifact_store import put_json + from app.ledger import docdraft + + try: + snapshot = docdraft.source_snapshot(documents=documents, chunks=chunks, datasource=datasource, + catalog=catalog, guidance=guidance, fixed_filters=fixed_filters) + artifact_id = await put_json(snapshot, kind=docdraft.SNAPSHOT_KIND, node_id=draft_id, + meta={"draft_id": draft_id, + "source_snapshot_version": docdraft.SNAPSHOT_VERSION}) + except Exception: # noqa: BLE001 - 快照落库失败不该把整份草稿判死,照实记「没有基线」 + logger.exception("来源快照落库失败(草稿 %s)", draft_id) + return None + return docdraft.snapshot_ref(artifact_id, snapshot) + + +def _prompt_trace(*, round: int, purpose: str, fitted: tuple[dict[str, dict], str, bool, bool], + model_id: str, salvaged: bool = False, groups: int | None = None) -> dict[str, Any]: + """记一次模型提示:这一轮实际让它看了哪几段原文、用的是哪一版提示词/解析、截断没有。 + + visible_chunk_ids 是**真正进了提示**的那几段。段落被 fit_material 整段丢掉时它不在这里,被截掉尾巴的那一段仍在这里 + (引用核对按截断后的内容算,尾巴上的话对不上)。这份记录是「模型当时看到了什么」的凭据,和来源快照各管一段: + 快照保原文,这里保可见范围。 + """ + kept, _tables, doc_truncated, catalog_truncated = fitted + from app.ledger import docdraft, draftplan + + return { + "round": round, + "purpose": purpose, + "model_id": model_id, + "prompt_version": draftplan.PROMPT_VERSION, + "parse_version": docdraft.PARSE_VERSION, + "visible_chunk_ids": sorted(str(c) for c in kept), + "visible_chars": {str(cid): len(str((chunk or {}).get("content") or "")) + for cid, chunk in kept.items()}, + "doc_truncated": bool(doc_truncated), + "catalog_truncated": bool(catalog_truncated), + "salvaged": bool(salvaged), + **({"groups": groups} if groups is not None else {}), + } + + +async def _capture_field_baseline(*, draft: Any, graph: dict[str, Any], workflow_id: str, + source_snapshot: dict[str, Any] | None, + accepted_revision: int = 1) -> dict[str, Any]: + """首次接受导入:把**被接受进图里的字段值**按 metric_id + field_path 存成 B,返回 payload 里要记的那几项。 + + 「接受」这一刻就是这份导入成功规范化、落进初始草稿图的那一刻(见 extract):取的是图上那张权威源头口径卡的指标 + (不是草稿 payload 里的快照,也不是草稿后来改成什么样)。存不下时返回空 dict:调用方不写 field_baseline, + 读接口照实说 baseline_unknown——不假装有基线,也不拿当前值倒填。 + """ + from app.ledger import fieldbaseline + + card_id, metrics = fieldbaseline.accepted_card(graph) + if not metrics: + return {} + ref = await fieldbaseline.put_metrics(metrics=metrics, card_id=card_id, workflow_id=workflow_id, + accepted_revision=accepted_revision, source_snapshot=source_snapshot, + draft_id=draft.id, accepted_by=draft.created_by) + if ref is None: + return {} + history = fieldbaseline.history(draft.payload if isinstance(draft.payload, dict) else {}) + return {fieldbaseline.REF_KEY: ref, fieldbaseline.HISTORY_KEY: [*history, ref]} + + async def extract(draft_id: str, *, run_trial: Any, save_trial: Any, trial_binding: Any) -> None: """后台起草:读文档的段落和数据目录,分组反复调模型直到覆盖完,收成一张多取数的草稿图、建工作流、再跑一次试跑。 @@ -257,6 +339,15 @@ async def extract(draft_id: str, *, run_trial: Any, save_trial: Any, trial_bindi 每轮可交多组能共用 SQL 的指标,按 uncovered 续写,直到覆盖完、没有新指标或到轮数/条数上限。每轮先提交进度和 已校验分组的检查点,再等待模型。材料指纹相同的重试可接续检查点;并行修复各用独立数据库会话。 + + **来源侧前置(K05)。** 读到材料的那一刻就把原文按内容寻址存进工件库(_capture_source),草稿 payload 只记 + source_snapshot 引用;每次模型提示实际看到了哪几段记进 prompts。引用核对只认实际进提示的段落(fit_material 的 + 结果),被截断丢掉的段落引用它核不上。checkpoint 仍旧只作任务恢复用——它记的是「哪些组已经起草好了」,不是 + 字段基线 B;来源内容的还原靠工件,两者不混。 + + **字段基线 B(K05)。** 这份导入成功规范化、收成图的那一刻(`_capture_field_baseline`),被接受进图里的字段值 + 按 metric_id + field_path 存成一件不可变工件,payload 记引用(field_baseline)并追加一条历史。之后人工按字段改 + 只改 L,不动这份 B;重导入拿它当基线(K11)。 """ from app.core.artifact_store import graph_hash from app.db.models import WorkflowVersion @@ -303,6 +394,17 @@ async def extract(draft_id: str, *, run_trial: Any, save_trial: Any, trial_bindi guidance = str(origin.get("guidance") or "") fixed_filters = str(origin.get("fixed_filters") or "") + + # 提取这一刻就把来源存下来:原文按内容寻址进工件库,草稿只记引用。重导入要拿来当 B 的是这份快照, + # 不是草稿现在的样子;存原文是为了还原,光有哈希还原不了。先提交一次会话,落工件时不再握着读事务。 + await session.commit() + source_snapshot = await _capture_source( + documents=[{"document_id": doc.id, "title": doc.title or doc.source or doc.id, + "source": doc.source or "", "collection": doc.collection or "", + "content": doc.content or ""} for doc in docs], + chunks=chunks, datasource=datasource, catalog=tables_text, guidance=guidance, + fixed_filters=fixed_filters, draft_id=draft_id) + alignment: dict[str, list[Any]] = {"new": [], "duplicate": [], "conflict": []} # 每组一组指标:{sql, entry_fields, metrics},循环结束时拼成一张图 blocks: list[dict[str, Any]] = [] @@ -316,6 +418,8 @@ async def extract(draft_id: str, *, run_trial: Any, save_trial: Any, trial_bindi catalog_truncated = False salvaged = False model_id = "" + #: 每次模型提示实际看到了哪几段(提示记录):visible_chunk_ids 与版本,见 _prompt_trace + prompts: list[dict[str, Any]] = [] from app.core.artifact_store import canonical_json, content_hash @@ -329,22 +433,39 @@ async def extract(draft_id: str, *, run_trial: Any, save_trial: Any, trial_bindi problems = list(previous.get("dropped") or []) def state() -> dict[str, Any]: - return {**_draft_payload(entries=entries, blocks=blocks, problems=problems, questions=questions, - uncovered=uncovered, progress=progress, doc_truncated=doc_truncated, - catalog_truncated=catalog_truncated, model_id=model_id, salvaged=salvaged), - "material_hash": material_hash, "checkpoint": {"groups": copy.deepcopy(blocks)}} + payload = _draft_payload(entries=entries, blocks=blocks, problems=problems, questions=questions, + uncovered=uncovered, progress=progress, doc_truncated=doc_truncated, + catalog_truncated=catalog_truncated, model_id=model_id, salvaged=salvaged, + source_snapshot=source_snapshot, prompts=prompts) + # 来源基线状态现算现写:有可还原的快照就是 known,没有就是 baseline_unknown。它只说明「当时的原文 + # 还原得出来」,不等于字段基线,也不等于这条口径验证通过。 + payload["source_baseline"] = docdraft.source_baseline(payload) + return {**payload, "material_hash": material_hash, + "checkpoint": {"groups": copy.deepcopy(blocks)}} try: for rnd in range(1, MAX_ROUNDS + 1): await session.commit() + # 先算一次材料:这一份既进提示,也拿来核对引用、记提示记录——两处用同一份,引用才核得上实际可见范围 + fitted = draftplan.fit_material(entries, chunks, guidance, datasource, tables_text, + covered, fixed_filters) + visible = fitted[0] async with SessionLocal() as planning: result = await draftplan.plan_groups(planning, docs=entries, chunks=chunks, guidance=guidance, datasource=datasource, tables_text=tables_text, covered=covered, - fixed=fixed_filters) + fixed=fixed_filters, fitted=fitted) + doc_truncated = doc_truncated or fitted[2] + catalog_truncated = catalog_truncated or fitted[3] + salvaged = salvaged or bool(result.get("salvaged")) + model_id = result.get("model_id") or model_id + prompts.append(_prompt_trace(round=rnd, purpose="plan", fitted=fitted, model_id=model_id, + salvaged=bool(result.get("salvaged")), + groups=len(result.get("groups") or []))) new_count = 0 failed: list[tuple[dict[str, Any], list[dict[str, Any]]]] = [] for raw_group in result.get("groups") or []: - plan, round_problems = draftplan.normalize_plan(raw_group, chunks, + # 引用核对只认实际进提示的段落:visible 里没有的段落,模型引用它也核不上 + plan, round_problems = draftplan.normalize_plan(raw_group, visible, allowed_tables=allowed_tables) fresh = _fresh_metrics(plan["metrics"], covered) if plan["sql"] and fresh: @@ -361,6 +482,12 @@ async def extract(draft_id: str, *, run_trial: Any, save_trial: Any, trial_bindi if failed: # 一组修不好不该拖垮别的组:每组独立重写一次,最多三组同时进行 semaphore = asyncio.Semaphore(3) + # 重写和起草的材料一样,但 fit 的入参不同(covered 是空的、fixed 照旧,见 repair_group): + # 先算一次,各次重写与引用核对共用同一份可见范围 + repair_fitted = draftplan.fit_material(entries, chunks, guidance, datasource, tables_text, + (), fixed_filters) + prompts.append(_prompt_trace(round=rnd, purpose="repair", fitted=repair_fitted, + model_id=model_id, groups=len(failed))) async def repair(raw: dict[str, Any], issues: list[dict[str, Any]]): async with semaphore: @@ -369,14 +496,14 @@ async def extract(draft_id: str, *, run_trial: Any, save_trial: Any, trial_bindi fixed = await draftplan.repair_group( repairing, group=raw, problems=issues, docs=entries, chunks=chunks, guidance=guidance, datasource=datasource, tables_text=tables_text, - fixed=fixed_filters) + fixed=fixed_filters, fitted=repair_fitted) except docdraft.DraftUnavailable as e: return None, [{"name": "重写这一组", "reason": str(e) or "AI 起草不可用"}] except Exception as e: # noqa: BLE001 - 单组重写出错只记这一组 return None, [{"name": "重写这一组", "reason": f"重写出错:{e}"}] if not fixed: return None, [] - return draftplan.normalize_plan(fixed, chunks, allowed_tables=allowed_tables) + return draftplan.normalize_plan(fixed, repair_fitted[0], allowed_tables=allowed_tables) repaired = await asyncio.gather(*(repair(raw, issues) for raw, issues in failed)) for (_raw, issues), item in zip(failed, repaired): @@ -396,10 +523,6 @@ async def extract(draft_id: str, *, run_trial: Any, save_trial: Any, trial_bindi questions = _merge_questions(questions, list(result.get("open_questions") or [])) uncovered = list(result.get("uncovered") or []) diagnostics = result.get("diagnostics") or diagnostics - doc_truncated = doc_truncated or bool(result.get("doc_truncated")) - catalog_truncated = catalog_truncated or bool(result.get("catalog_truncated")) - salvaged = salvaged or bool(result.get("salvaged")) - model_id = result.get("model_id") or model_id progress = {"round": rnd, "covered": len(covered), "uncovered": len(uncovered)} # 每轮先落一次库:这一轮要等一次模型调用,页面这时就能显示「第几轮、起草了几条、还剩几条」 draft.payload = state() @@ -465,9 +588,17 @@ async def extract(draft_id: str, *, run_trial: Any, save_trial: Any, trial_bindi await session.flush() session.add(WorkflowVersion(workflow_id=workflow.id, version=1, graph=graph, graph_hash=graph_hash(graph), note="从业务文档分组生成")) + # 落字段基线走的是工件库的另一个会话:先把工作流和 v1 提交掉,别让两个会话同时握着写锁(和 _capture_source + # 同一个道理)。提交之后 draft / workflow 仍然可用(SessionLocal 是 expire_on_commit=False)。 + await session.flush() + await session.commit() + # 首次接受导入:接受的那一刻就把被接受的字段值存成 B(K05,按 metric_id + field_path)。存的是**图里那 + # 一份**(接受的就是它),带上这次抽取的来源快照引用和接受版本;存不下时不写这一项(照实说没基线)。 + baseline = await _capture_field_baseline(draft=draft, graph=graph, workflow_id=workflow.id, + source_snapshot=source_snapshot) payload = { **state(), "workflow_id": workflow.id, "open_questions": asked, - "alignment": alignment, + "alignment": alignment, **baseline, } except docdraft.DraftUnavailable as e: draft.error = str(e) or "AI 起草不可用" @@ -494,7 +625,9 @@ async def extract(draft_id: str, *, run_trial: Any, save_trial: Any, trial_bindi started_by=draft.created_by, entry_fields=_merged_fields(blocks)) except Exception as e: # noqa: BLE001 - 试运行出错也要写进 payload,不能让界面停在「试运行中」 logger.exception("草稿 %s 的试运行出错", draft_id) - trial = {**trial_binding(1, graph, values), "run_id": "", "status": "failed", "error": f"试运行出错:{e}"} + # 这一条试运行也要有稳定身份(K05 的验证记录按它去重/认得是哪一次):出错这条没有运行,trial_id 由这里给 + trial = {**trial_binding(1, graph, values), "trial_id": uuid4().hex, "run_id": "", + "status": "failed", "error": f"试运行出错:{e}"} await save_trial(draft_id, trial) diff --git a/backend/app/ledger/bindings.py b/backend/app/ledger/bindings.py new file mode 100644 index 00000000..864c8201 --- /dev/null +++ b/backend/app/ledger/bindings.py @@ -0,0 +1,650 @@ +"""版本化的受控 SQL 模板绑定(K04):业务定义里的「统计时间口径」「退款规则」怎么落到取数 SQL 上。 + +**首版只有一种绑定**(binder=controlled_template, version=1):取数节点 data.config.binding 里显式声明 +一份受控模板——模板里用 `[[time_role]]`、`[[refund_rule]]` 这样的业务 token 占位,`snippets` 说明每个 token 的 +每个业务值展开成哪一段 SQL,`values` 说明这一版现在取的是哪个值。展开只做一次、在**作者侧**:K03 的字段变更服务 +(app/ledger/changes.py)把定义和这段 SQL 在同一个事务里改掉,执行期绝不再按业务语义重推(A09)。SQL 里的 +`{{ input.字段 }}` 仍归 K01,执行期照旧按入口渲染,和业务 token 是两回事。 + +**不做通用 AST 改写,也不建中央映射表。** 这里没有 SQL 解析器:判定「能不能确定性同步」只看两件事——节点上有一份 +形状合法、版本认得的绑定,而且**当前 args.sql 正好就是这份模板按当前业务值展开出来的**(哈希一致 + 逐字相等)。 +对不上的(SQL 被手工改过、模板里根本没有这个 token 的落点、映射里没有这个值、同一条 SQL 上的两个指标说法打架) +一律**不同步**,照实说 unsupported / needs_update,并把原因、影响对象和该做什么写在报告里。业务词汇表(哪些字段、 +每个字段允许哪些值)是这一层的代码常量,不是一张表、也不按资产复制。 + +**aligned 只说「定义和实现同步」**(4.5):不等于业务验证通过,也不改变 semantic_unverified、SQL 检查和质量结论。 +旧资产(指标定义里压根没有这两个字段)不在这套判定里——状态是 unbound/not_declared,行为一个字不变。 + +**这一层给别人的接口**:`read` / `declared`(读数)、`shape_problem`(绑定本身的形状、版本与取值域)、`render` +(按业务值把模板确定性展开)、`analyze` / `plan` / `blocking`(定义 vs 实现的判定、可同步的新配置、拦运行的那句话)、 +`capability`(读接口的能力描述)、`fingerprint` / `sql_hash` / `snapshot_material`(绑定指纹与查询快照材料)。 +写侧只有 K03 的字段变更服务会改这些值(changes.py 的 _sync_bindings),别的入口一律只读。 +""" +from __future__ import annotations + +import copy +import re +from collections.abc import Iterable, Mapping +from dataclasses import dataclass, field, replace +from typing import Any + +#: 绑定写在取数节点 data.config 的这个键上 +KEY = "binding" +#: 首版认的 binder 与版本 +BINDER = "controlled_template" +BINDER_VERSION = 1 +#: 业务 token 的写法:[[time_role]] +TOKEN = "[[{name}]]" + +#: 绑定的几个状态(4.5)。aligned 只表示定义和实现同步 +ALIGNED = "aligned" +NEEDS_UPDATE = "needs_update" +UNSUPPORTED = "unsupported" +#: 这张卡(这些取数节点)压根没声明业务字段:不判同步,旧资产就是这个状态 +UNBOUND = "unbound" +#: 单条取数节点上的指标没声明业务字段:这个节点不参与判定 +NOT_DECLARED = "not_declared" + +#: 该怎么处置(给界面和报告读:拿它决定要不要显示「去画布改」这类按钮) +FIX_NONE = "none" # 已经对齐,什么也不用做 +FIX_SYNC = "sync" # 定义变了,可以确定性同步 SQL +FIX_AUTHOR = "author" # 要作者侧补/改受控绑定(没有绑定、没有落点、映射没有这个值) +FIX_MANUAL = "manual" # 人先要拿主意(指标之间说法打架、SQL 被手工改过) + +#: 查询快照里记绑定材料的键(engine/nodes/tools 放,tools/datasource 读) +SNAPSHOT_KEY = "caliber_binding" + + +@dataclass(frozen=True) +class Choice: + """一个业务值:机器值 + 给人看的说法。""" + + value: str + label: str + + +@dataclass(frozen=True) +class BusinessField: + """一个业务字段:给人看的名字、允许的值、一句话说明。""" + + field: str + label: str + choices: tuple[Choice, ...] + help: str = "" + + def values(self) -> list[str]: + return [choice.value for choice in self.choices] + + def label_of(self, value: Any) -> str: + return next((choice.label for choice in self.choices if choice.value == value), str(value or "")) + + +#: 首版认识的业务字段与允许值(词汇表在这一层,不建表、不按资产复制) +FIELDS: dict[str, BusinessField] = { + "time_role": BusinessField( + "time_role", "统计时间口径", + (Choice("order_time", "按下单时间"), Choice("payment_time", "按支付时间")), + "这条指标的统计口径按哪个时间点算:下单时间还是支付时间"), + "refund_rule": BusinessField( + "refund_rule", "退款处理", + (Choice("include_all", "全部计入"), Choice("exclude_full_refund", "排除全额退款")), + "退款订单算不算进来:全额退款排除、部分退款保留"), +} + + +def editable_fields() -> list[dict[str, Any]]: + """服务端能力描述里的 editable_fields:能按字段改的业务定义、允许的值和说明。""" + return [{"field": spec.field, "label": spec.label, "values": spec.values(), + "value_labels": {choice.value: choice.label for choice in spec.choices}, "help": spec.help} + for spec in FIELDS.values()] + + +def declared(metric: Any) -> dict[str, str]: + """一条指标声明了哪些业务值:只认词汇表里的字段,值不是字符串或不在允许值里的照实带回(交给判定说原因)。""" + if not isinstance(metric, Mapping): + return {} + out: dict[str, str] = {} + for name in FIELDS: + value = metric.get(name) + if isinstance(value, str) and value.strip(): + out[name] = value.strip() + elif value not in (None, ""): + out[name] = str(value) + return out + + +def _config_of(node: Any) -> dict[str, Any]: + data = node.get("data") if isinstance(node, Mapping) else None + config = data.get("config") if isinstance(data, Mapping) else None + return config if isinstance(config, dict) else {} + + +def read(node: Any) -> dict[str, Any] | None: + """取数节点上的绑定原文(形状不对时也照原样交回,由 shape_problem 说哪里不对)。""" + binding = _config_of(node).get(KEY) + return binding if isinstance(binding, dict) else None + + +def _sql_of(config: Mapping[str, Any]) -> str | None: + args = config.get("args") + sql = args.get("sql") if isinstance(args, Mapping) else None + return sql if isinstance(sql, str) else None + + +#: 模板里认得出的业务 token([[time_role]]) +_TOKEN_RE = re.compile(r"\[\[([A-Za-z_][A-Za-z0-9_]*)\]\]") +#: 模板里所有 [[…]] 的写法(认不出的也要照原文报出来) +_ANY_TOKEN_RE = re.compile(r"\[\[[^\]]*\]\]") + + +def _tokens_of(template: Any) -> list[str]: + """受控模板里用到的业务字段,按出现顺序去重。裸写的和写在引号里的都算——看的是 token 本身。""" + return list(dict.fromkeys(_TOKEN_RE.findall(str(template or "")))) + + +def _stray_tokens(template: Any) -> list[str]: + """模板里 `[[…]]` 的写法但不属于任何已知字段的那些(照原文)。""" + known = {TOKEN.format(name=name) for name in FIELDS} + return sorted({token for token in _ANY_TOKEN_RE.findall(str(template or "")) if token not in known}) + + +class UnresolvedToken(ValueError): + """受控模板里的 token 这次展开不了(没有值、或没有展开写法):宁可拒绝,也不把 [[…]] 留在 SQL 里。""" + + +def sql_hash(sql: str) -> str: + from app.core.artifact_store import content_hash + + return content_hash(str(sql or "")) + + +def render(template: str, snippets: Mapping[str, Mapping[str, str]], values: Mapping[str, str]) -> str: + """把受控模板里的 [[字段]] 按业务值展开成 SQL(纯字符串替换,确定性)。 + + **展开不了的 token 直接抛 UnresolvedToken**(没有值、或者没有展开写法):宁可拒绝一次变更,也不把 + `[[time_role]]` 这样的占位原样留在 SQL 里发出去或者写回 args.sql——那会让人以为业务规则已经落进 SQL 了。 + 调用方(analyze / plan / snapshot_material)在展开之前都先过 shape_problem,走到这里还缺就是形状那边漏了。 + """ + out = str(template or "") + for name in _tokens_of(out): + if name not in FIELDS: + raise UnresolvedToken(f"{TOKEN.format(name=name)} 不是认识的业务字段(只认 {'、'.join(FIELDS)})") + value = values.get(name) + snippet = (snippets.get(name) or {}).get(value) if value is not None else None + if not isinstance(snippet, str) or not snippet.strip(): + raise UnresolvedToken( + f"{TOKEN.format(name=name)} 展开不了" + f"({'当前业务值里没有' if value is None else '允许映射里没有'}「{FIELDS[name].label}」的取值)") + out = out.replace(TOKEN.format(name=name), snippet) + return out + + +def shape_problem(binding: Any) -> str | None: + """绑定本身的形状/版本/取值域哪里不对;没问题就是 None。 + + 这是「这条 SQL 是不是受控模板写出来的」的一部分:binder 不认得、版本比这一版新、缺模板,以及**模板、允许映射 + 和当前业务值三边的 token 对不上**——模板里用了却没有值(展开不了,不能算 aligned,更不能把 [[…]] 写进 SQL)、 + 允许映射里有却没用进模板(这条 SQL 表示不了那个业务值)、模板里的 token 没有展开写法。每一句都点名是哪个字段。 + """ + if not isinstance(binding, Mapping): + return "这个取数节点没有受控绑定(data.config.binding):定义改了,SQL 不会跟着改" + binder = str(binding.get("binder") or "") + if binder != BINDER: + return f"认不出这个绑定器「{binder or '(空)'}」:首版只支持 {BINDER}" + version = binding.get("version") + if version != BINDER_VERSION: + return f"绑定的版本是 {version!r}:这一版只认 {BINDER_VERSION},不按更新的写法重解释旧绑定(A09)" + for key, what in (("domain", "业务域"), ("mapping_version", "映射版本")): + if not str(binding.get(key) or "").strip(): + return f"绑定缺{what}({key}):映射要带版本才认得出它是什么时候的写法" + template = binding.get("template") + if not isinstance(template, str) or not template.strip(): + return "绑定里没有受控模板(template)" + snippets = binding.get("snippets") + if not isinstance(snippets, Mapping) or not snippets: + return "绑定里没有允许映射(snippets)" + values = binding.get("values") + if not isinstance(values, Mapping): + return "绑定里没有当前业务值(values)" + for name, by_value in snippets.items(): + spec = FIELDS.get(str(name)) + if spec is None: + return f"允许映射里有不认识的字段「{name}」:首版只认 {'、'.join(FIELDS)}" + if not isinstance(by_value, Mapping) or not by_value: + return f"「{spec.label}」没有允许映射" + for value, snippet in by_value.items(): + if str(value) not in spec.values(): + return f"「{spec.label}」的允许映射里有不认识的取值「{value}」" + if not isinstance(snippet, str) or not snippet.strip(): + return f"「{spec.label}」的「{spec.label_of(value)}」没有展开写法" + for name, value in values.items(): + spec = FIELDS.get(str(name)) + if spec is None: + return f"当前业务值里有不认识的字段「{name}」" + if str(value) not in (snippets.get(name) or {}): + return f"「{spec.label}」现在是「{value}」,但允许映射里没有它" + if stray := _stray_tokens(template): + return f"受控模板里有认不出的 token:{'、'.join(stray)}(业务 token 只认 {'、'.join(FIELDS)})" + used = _tokens_of(template) + mapped = [str(name) for name in snippets] + valued = [str(name) for name in values] + if dead := [name for name in mapped if name not in used]: + return (f"允许映射里有「{FIELDS[dead[0]].label}」,但模板里没有 {TOKEN.format(name=dead[0])} 的落点:" + "这条 SQL 表示不了这个业务值(要么把它写进模板,要么别声明它)") + if missing := [name for name in used if name not in snippets]: + return (f"模板里的 {TOKEN.format(name=missing[0])} 没有展开写法:" + f"允许映射里缺「{FIELDS[missing[0]].label}」") + if absent := [name for name in used if name not in valued]: + return (f"受控模板用了 {TOKEN.format(name=absent[0])},但当前业务值里没有它:" + f"先补上「{FIELDS[absent[0]].label}」的取值——不能把一个没展开的模板当 SQL 发出去") + return None + + +def fingerprint(binding: Mapping[str, Any]) -> str: + """绑定的内容指纹(确定性):绑定器、版本、业务域与映射版本、当前值、模板与允许映射、当前 SQL 的哈希。 + + 改了业务值(同一份模板换一种展开)指纹就变;同一份绑定在哪张图上算都是同一个值。""" + from app.core.artifact_store import canonical_json, content_hash + + return content_hash(canonical_json({ + "binder": str(binding.get("binder") or ""), "version": binding.get("version"), + "domain": str(binding.get("domain") or ""), "mapping_version": binding.get("mapping_version"), + "values": {str(k): str(v) for k, v in (binding.get("values") or {}).items()}, + "template": str(binding.get("template") or ""), + "snippets": {str(k): {str(v): str(s) for v, s in (by_value or {}).items()} + for k, by_value in (binding.get("snippets") or {}).items()}, + "rendered_hash": str(binding.get("rendered_hash") or ""), + })) + + +# ========================================================================== +# 判定:这张卡的定义和它读的取数节点上的绑定对不对得上 +# ========================================================================== + + +@dataclass(frozen=True) +class NodeState: + """一个取数节点上的判定结果。""" + + node_id: str + status: str + reason: str + fix: str + #: 这个节点上指标声明的业务值(每个字段唯一一个值;打架时的值不进这里,只在 reason 里说) + declared: dict[str, str] + #: 绑定里现在的值 + values: dict[str, str] + metrics: tuple[str, ...] + binding_fingerprint: str = "" + + def as_dict(self) -> dict[str, Any]: + out = {"node_id": self.node_id, "status": self.status, "reason": self.reason, "fix": self.fix, + "declared": dict(self.declared), "values": dict(self.values), "metrics": list(self.metrics)} + if self.binding_fingerprint: + out["binding_fingerprint"] = self.binding_fingerprint + return out + + +@dataclass(frozen=True) +class Report: + """一张卡的业务定义 vs 它读的取数节点上的绑定:状态、原因、影响对象、该做什么,以及能同步时要写什么。""" + + status: str + reason: str + fix: str + metrics: tuple[str, ...] + nodes: tuple[NodeState, ...] + #: 可以确定性同步时:node_id → 新的 data.config(已经只改了 args.sql 与 binding 两处) + configs: dict[str, dict[str, Any]] = field(default_factory=dict) + #: 每条指标声明的业务值:metric_id → {字段: 值}(界面按指标显示「这一条按支付时间算」用它) + metric_values: dict[str, dict[str, str]] = field(default_factory=dict) + + @property + def aligned(self) -> bool: + return self.status == ALIGNED + + @property + def blocked(self) -> bool: + """定义和实现对不上(或对不上但同步不了):这一类不许发起运行、不许把旧 SQL 的结果当新定义。""" + return self.status in (NEEDS_UPDATE, UNSUPPORTED) + + @property + def fingerprints(self) -> dict[str, str]: + return {node.node_id: node.binding_fingerprint for node in self.nodes if node.binding_fingerprint} + + def as_dict(self, *, with_nodes: bool = True) -> dict[str, Any]: + out: dict[str, Any] = {"status": self.status, "reason": self.reason, "fix": self.fix, + "metrics": list(self.metrics), "checked": True, + "metric_values": {k: dict(v) for k, v in self.metric_values.items()}} + if self.status == UNSUPPORTED: + out["unsupported_reason"] = self.reason + if self.fingerprints: + out["binding_fingerprints"] = self.fingerprints + if with_nodes: + out["nodes"] = [node.as_dict() for node in self.nodes] + return out + + +def _locate(graph: Mapping[str, Any], metrics: Iterable[Mapping[str, Any]]) -> tuple[dict[str, list[str]], dict[str, str]]: + """这些指标各自读到哪几个取数节点,以及**定位不到**的指标各自为什么。 + + 只认调用工具节点(type=tool)上的 `cell(nodes.X, 0, '列')`:绑定写在取数节点上。式子读的是 code / merge 这类 + 别的节点、读的是 vars / rows 这种拿不到节点身份的写法、或者式子根本读不出来时,这条指标定位不到——调用方据此 + 报 unsupported,**不能当成「没声明业务字段」放行**(那等于让上游那一版的定义落到旧的实现上)。 + """ + from app.apps.tree import node_map + from app.engine.expressions import ExpressionError, cell_parts, leaf_refs, parse_expression + from app.engine.labels import type_label + from app.engine.metric_spec import metric_expressions + + nodes = node_map(graph) + located: dict[str, list[str]] = {} + problems: dict[str, str] = {} + for metric in metrics: + metric_id = str(metric.get("id") or "") + if not metric_id: + continue + paths = metric_expressions(metric) + if paths is None: + problems[metric_id] = "它的算法读不出输入(指标类型认不出,或者式子不是字符串)" + continue + found: list[str] = [] + reason = "" + for path in paths: + try: + tree = parse_expression(path)[0] + except ExpressionError: + reason = reason or "式子读不出来(表达式语法不对)" + continue + for leaf in leaf_refs(tree): + parts = cell_parts(leaf) + if parts is None or not parts[0].startswith("nodes."): + reason = reason or ("式子里有不是取数节点某一格的读取:本版只认「从取数节点取某一格」这一种写法" + "(引用的要是 vars 或 rows 这类,也定位不到取数节点)") + continue + node_id = parts[0][len("nodes."):] + node = nodes.get(node_id) + if node is None: + reason = reason or f"式子读到的节点「{node_id}」不在这张图上" + elif node.get("type") != "tool": + reason = reason or (f"式子读的是节点「{node_id}」({type_label(node.get('type'))}),不是取数节点") + elif node_id not in found: + found.append(node_id) + if found: + located[metric_id] = found + else: + problems[metric_id] = reason or "它的算法里没有取数节点(外部常量)" + return located, problems + + +def _readers(graph: Mapping[str, Any], metrics: Iterable[Mapping[str, Any]]) -> dict[str, list[str]]: + """取数节点 id → 读它的指标 id(只看能定位的那种读取:cell(nodes.节点, 0, '列'))。 + + 别的模块(ledger/closure 的依赖闭包、K08)按这个形状读「哪些指标读哪个取数节点」,它就是 _locate 反过来的一份。 + 定位不到的那些指标不在结果里:它们的业务声明由 _locate 单独交回原因,analyze 据此报 unsupported,不当成 + 「没声明业务字段」放行。 + """ + located, _problems = _locate(graph, metrics) + out: dict[str, list[str]] = {} + for metric_id, node_ids in located.items(): + for node_id in node_ids: + out.setdefault(node_id, []).append(metric_id) + return out + + +def _node_of(graph: Mapping[str, Any], node_id: str) -> dict[str, Any] | None: + return next((n for n in graph.get("nodes") or [] + if isinstance(n, Mapping) and str(n.get("id")) == node_id), None) + + +def _conflicts(declared_by_metric: Mapping[str, Mapping[str, str]]) -> dict[str, list[str]]: + """同一个取数节点上,几个指标对同一个业务字段的说法打架:字段 → 出现过的值(按出现顺序)。""" + seen: dict[str, list[str]] = {} + for values in declared_by_metric.values(): + for name, value in values.items(): + if value not in seen.setdefault(name, []): + seen[name].append(value) + return {name: values for name, values in seen.items() if len(values) > 1} + + +def _declared_here(declared_by_metric: Mapping[str, Mapping[str, str]]) -> dict[str, str]: + """这个节点上声明的业务值(没有打架的字段),冲突的字段不进这里(由 _conflicts 说)。""" + out: dict[str, str] = {} + for values in declared_by_metric.values(): + for name, value in values.items(): + out.setdefault(name, value) + return out + + +def _node_state(node_id: str, graph: Mapping[str, Any], declared_by_metric: Mapping[str, Mapping[str, str]]) -> NodeState: + metrics = tuple(declared_by_metric) + node = _node_of(graph, node_id) or {} + binding = read(node) + if not declared_by_metric: + return NodeState(node_id, NOT_DECLARED, + "这个取数节点上的指标没有声明统计时间口径和退款规则:按旧资产处理,不判同步", + FIX_NONE, {}, {}, metrics, fingerprint(binding) if binding else "") + if conflicts := _conflicts(declared_by_metric): + detail = ";".join(f"「{FIELDS[name].label}」有的指标说{_value_text(name, values[0])}、" + f"有的说{_value_text(name, values[1])}" for name, values in conflicts.items()) + return NodeState(node_id, NEEDS_UPDATE, + f"同一条取数 SQL 上的指标说法不一致({detail}):一个节点只有一份 SQL,先统一再改", + FIX_MANUAL, {}, {}, metrics, fingerprint(binding) if binding else "") + declared = _declared_here(declared_by_metric) + if binding is None: + return NodeState(node_id, NEEDS_UPDATE, + "这个取数节点没有受控绑定(data.config.binding):定义改了,SQL 不会跟着改", + FIX_AUTHOR, declared, {}, metrics) + if problem := shape_problem(binding): + return NodeState(node_id, UNSUPPORTED, problem, FIX_AUTHOR, declared, + {str(k): str(v) for k, v in (binding.get("values") or {}).items()}, metrics, + fingerprint(binding)) + snippets = {str(k): dict(v) for k, v in (binding.get("snippets") or {}).items()} + values = {str(k): str(v) for k, v in (binding.get("values") or {}).items()} + config = _config_of(node) + sql = _sql_of(config) + if sql is None: + return NodeState(node_id, UNSUPPORTED, "这个取数节点没有一条能读的取数 SQL(args.sql)", FIX_AUTHOR, + declared, values, metrics, fingerprint(binding)) + for name, value in declared.items(): + spec = FIELDS[name] + if name not in snippets: + return NodeState(node_id, UNSUPPORTED, + f"这条 SQL 里没有「{spec.label}」的落点(受控模板里没有 {TOKEN.format(name=name)}):" + "这条取数不是受控模板写出来的,改不了", FIX_AUTHOR, declared, values, metrics, + fingerprint(binding)) + if value not in snippets[name]: + return NodeState(node_id, UNSUPPORTED, + f"「{spec.label}」的映射里没有{_value_text(name, value)}:这条 SQL 表示不了它", + FIX_AUTHOR, declared, values, metrics, fingerprint(binding)) + if _literal_copy(config): + # 组合式问数(ledger/compose)拷进来的节点:args 已经是服务端按固定那一版的受控模板渲染好的字面语句, + # 参数值渲染进去了(K01 的契约与它绑定,改过契约就作废、按普通节点判)。这时不能再拿 args.sql 和「模板 + # 展开」逐字比——那比的是值渲染进去之前的形态。业务语义在派生那一刻已经按源版本核过(derive.load_pinned), + # 这里只比这一版的指标定义和副本上记的业务值对不对得上:对不上就拦住(那份数不是这个定义算出来的) + if all(values.get(name) == value for name, value in declared.items()): + return NodeState(node_id, ALIGNED, + "这份取数是服务端按固定那一版口径的受控模板渲染好的副本(参数只渲染一次):定义和它一致" + "(aligned 只说这两边对得上,不等于业务验证通过)", FIX_NONE, declared, values, + metrics, fingerprint(binding)) + detail = ";".join( + f"「{FIELDS[name].label}」定义说{_value_text(name, value)}、副本里是{_value_text(name, values.get(name))}" + for name, value in declared.items() if values.get(name) != value) + return NodeState(node_id, NEEDS_UPDATE, + f"这份取数是按固定那一版口径渲染好的副本,它的业务值和这一版的定义对不上({detail}):" + "回到源口径卡把它同步好,再重新组合", FIX_AUTHOR, declared, values, metrics, + fingerprint(binding)) + try: + rendered = render(str(binding.get("template") or ""), snippets, values) + except UnresolvedToken as e: + # 形状校验已经拦过展开不了的绑定;真走到这里(比如别的入口写进来的数据)也不能放行 + return NodeState(node_id, UNSUPPORTED, f"受控模板展开不了:{e}", FIX_AUTHOR, declared, values, metrics, + fingerprint(binding)) + if sql_hash(sql) != str(binding.get("rendered_hash") or "") or rendered != sql: + return NodeState(node_id, NEEDS_UPDATE, + "当前 SQL 不是这份绑定展开出来的(被手工改过,或绑定记录已经过时):" + "要么把 SQL 改回模板展开的样子,要么重新声明这份绑定", FIX_MANUAL, declared, values, + metrics, fingerprint(binding)) + if all(values.get(name) == value for name, value in declared.items()): + return NodeState(node_id, ALIGNED, + "定义和取数 SQL 同步(aligned 只说这两边对得上,不等于业务验证通过)", FIX_NONE, + declared, values, metrics, fingerprint(binding)) + return NodeState(node_id, NEEDS_UPDATE, + "定义改了,绑定里还是旧的:可以按受控模板确定性地把 SQL 改过来", FIX_SYNC, + declared, values, metrics, fingerprint(binding)) + + +def _value_text(name: str, value: Any) -> str: + spec = FIELDS.get(name) + text = spec.label_of(value) if spec else str(value) + return f"「{text}」" + + +def _literal_copy(config: Mapping[str, Any]) -> bool: + """这个节点是不是「参数已经渲染成字面语句」的副本(ledger/params 的契约,K01):组合式问数拷出来的那些。 + + 契约要核对过哈希才算(helper 自己判):args 被改过之后契约作废,这里就是 False,按普通节点照旧拿 args.sql + 和模板展开比。 + """ + from app.ledger import params as sql_params + + return bool(sql_params.is_literal(config, "tool")) + + +def analyze(graph: Mapping[str, Any], card_id: str, metrics: Iterable[Mapping[str, Any]] | None = None) -> Report: + """算这张卡的业务定义和取数节点上绑定的对得上的程度(读接口、写服务、派生拦阻、运行前检查都用这一份)。 + + metrics 不给就读图上这张卡的指标(源头卡);**转抄卡(caliber_from)必须把实际生效的指标传进来**——钉住那一版 + 的定义,而且式子已经按 caliber_from.nodes 的源→本地映射改写到本图的取数节点 id 上(engine/nodes/metrics 的 + _pinned_caliber 就是这么改的)。不传的话转抄卡在本图里没有自己的 metrics,会被当成「没声明业务字段」而放行, + 上游定义和本地那句 SQL 的差别就没人管了。 + + **unbound 只留给「确实一条业务声明都没有」的旧资产。** 有指标声明了时间口径/退款规则、但它的算法定位不到任何 + 取数节点(读 code / merge 这类别的节点、式子写的是 vars / rows、式子读不出来……)时,报 unsupported:那种情况下 + 没人能证明这条 SQL 实现了声明的业务值,放行就等于让定义落到旧的实现上。 + """ + from app.apps.tree import node_map + + definitions = list(metrics) if metrics is not None else [ + m for m in ((node_map(graph).get(str(card_id)) or {}).get("config") or {}).get("metrics") or [] + if isinstance(m, Mapping)] + metric_values: dict[str, dict[str, str]] = {} + for metric in definitions: + if not isinstance(metric, Mapping) or not metric.get("id"): + continue + values = declared(metric) + if values: + metric_values[str(metric["id"])] = values + if not metric_values: + return Report(UNBOUND, "这张卡没有指标声明统计时间口径和退款规则:按旧资产处理,不判绑定同步", + FIX_NONE, (), ()) + declared_metrics = [m for m in definitions if isinstance(m, Mapping) and m.get("id") and declared(m)] + located, unlocated = _locate(graph, declared_metrics) + by_node: dict[str, dict[str, dict[str, str]]] = {} + for metric_id, node_ids in located.items(): + for node_id in node_ids: + by_node.setdefault(node_id, {})[metric_id] = metric_values[metric_id] + + states = tuple(_node_state(node_id, graph, declared_by_metric) for node_id, declared_by_metric in by_node.items()) + declared_ids = tuple(metric_values) + if unlocated: + # 有声明、定位不到:不能算「没声明」而放行。原因按指标逐条给出,影响对象是这些指标(metric_values 留着, + # 界面才知道它声明了什么、在等什么) + detail = ";".join(f"「{metric_id}」{reason}" for metric_id, reason in list(unlocated.items())[:3]) + more = f"(另有 {len(unlocated) - 3} 条同样的问题)" if len(unlocated) > 3 else "" + reason = (f"有指标声明了业务口径,但定位不到它读的取数节点:{detail}{more}。" + "绑定按取数节点算,定位不到就没法证明这条 SQL 实现了声明的业务值:" + "请把这条指标改成读取数节点某一格的写法,或者在取数节点上声明受控绑定") + return Report(UNSUPPORTED, reason, FIX_AUTHOR, declared_ids, states, metric_values=metric_values) + + worst = UNSUPPORTED if any(s.status == UNSUPPORTED for s in states) else ( + NEEDS_UPDATE if any(s.status == NEEDS_UPDATE for s in states) else ALIGNED) + first = next((s for s in states if s.status == worst), states[0]) + reason = first.reason if worst != ALIGNED else ( + "这一版的统计时间口径和退款规则和取数 SQL 是同步的(aligned 只说两边对得上,不等于业务验证通过)") + fix = first.fix if worst != ALIGNED else FIX_NONE + return Report(worst, reason, fix, declared_ids, states, metric_values=metric_values) + + +def plan(graph: Mapping[str, Any], card_id: str, metrics: Iterable[Mapping[str, Any]] | None = None) -> Report: + """在 analyze 之上算出可以确定性同步的取数节点配置;有一条同步不了就一条也不改(同事务里要么全落要么不落)。 + + 新配置是在**原节点配置的深拷贝**上只改两处:args.sql(模板按新业务值展开)和 binding(values / rendered_hash / + fingerprint)。没提到的键、别的节点、图上的扩展字段一个字不动。 + """ + report = analyze(graph, card_id, metrics) + syncable = [s for s in report.nodes if s.fix == FIX_SYNC] + if not syncable or any(s.fix not in (FIX_NONE, FIX_SYNC) for s in report.nodes if s.status != NOT_DECLARED): + return report + configs: dict[str, dict[str, Any]] = {} + for state in syncable: + node = _node_of(graph, state.node_id) or {} + binding = read(node) or {} + config = copy.deepcopy(_config_of(node)) + snippets = {str(k): dict(v) for k, v in (binding.get("snippets") or {}).items()} + values = {**{str(k): str(v) for k, v in (binding.get("values") or {}).items()}, **state.declared} + try: + sql = render(str(binding.get("template") or ""), snippets, values) + except UnresolvedToken as e: + # 展开不了就一条也不写:宁可停在 needs_update,也不把 [[time_role]] 原样写回 args.sql + return replace(report, status=UNSUPPORTED, fix=FIX_AUTHOR, configs={}, + reason=f"受控模板展开不了,没有改动 SQL:{e}") + updated = {**binding, "values": values, "rendered_hash": sql_hash(sql)} + updated["fingerprint"] = fingerprint(updated) + args = config.get("args") + config["args"] = {**(dict(args) if isinstance(args, Mapping) else {}), "sql": sql} + config[KEY] = updated + configs[state.node_id] = config + return Report(report.status, report.reason, report.fix, report.metrics, report.nodes, configs, + report.metric_values) + + +def blocking(report: Report) -> str | None: + """定义和实现不一致时给调用方的那句话(发起运行之前拦);一致或旧资产时是 None。""" + return report.reason if report.blocked else None + + +def capability(graph: Mapping[str, Any], card_id: str, + metrics: Iterable[Mapping[str, Any]] | None = None) -> dict[str, Any]: + """读接口的服务端能力描述:能按字段改的业务定义、允许值、现在的值、同步状态、不支持的原因、影响对象和动作。 + + **不给模板、不给 snippets、不给 SQL**:这几样是作者侧的实现细节,界面只需要知道业务值和状态。 + """ + report = analyze(graph, card_id, metrics) + current: dict[str, str] = {} + for node in report.nodes: + for name, value in node.values.items(): + current.setdefault(name, value) + return {"editable_fields": editable_fields(), "current": current, **report.as_dict()} + + +def snapshot_material(config: Mapping[str, Any], args: Any) -> dict[str, Any] | None: + """查询快照里记的绑定材料:这条 SQL 是哪份绑定的哪一次展开。 + + 只在**节点配置里那条 SQL 正好是这份绑定展开出来的**时候给(哈希一致 + 逐字相等):对不上就不写,不拿一份过时的 + 绑定去解释这条实际执行过的语句。核的是节点配置里那条({{ input.* }} 还在里面),不是这次渲染完的字面语句——所以 + 组合式问数拷进来、参数已经渲染成字面值的节点不记这一项(宁可没有,也不记一份对不上的)。不给模板正文和 snippets + (查询快照已经记了实际语句本身)。 + """ + binding = config.get(KEY) if isinstance(config, Mapping) else None + if not isinstance(binding, Mapping) or shape_problem(binding): + return None + sql = args.get("sql") if isinstance(args, Mapping) else None + if not isinstance(sql, str): + return None + snippets = {str(k): dict(v) for k, v in (binding.get("snippets") or {}).items()} + values = {str(k): str(v) for k, v in (binding.get("values") or {}).items()} + if sql_hash(sql) != str(binding.get("rendered_hash") or ""): + return None + if render(str(binding.get("template") or ""), snippets, values) != sql: + return None + return {"binder": str(binding.get("binder") or ""), "version": binding.get("version"), + "domain": str(binding.get("domain") or ""), "mapping_version": binding.get("mapping_version"), + "values": values, "rendered_hash": str(binding.get("rendered_hash") or ""), + "fingerprint": fingerprint(binding)} + + +__all__ = ["ALIGNED", "BINDER", "BINDER_VERSION", "FIELDS", "FIX_AUTHOR", "FIX_MANUAL", "FIX_NONE", "FIX_SYNC", + "KEY", "NEEDS_UPDATE", "NOT_DECLARED", "SNAPSHOT_KEY", "TOKEN", "UNBOUND", "UNSUPPORTED", "BusinessField", + "Choice", "NodeState", "Report", "analyze", "blocking", "capability", "declared", "editable_fields", + "fingerprint", "plan", "read", "render", "shape_problem", "snapshot_material", "sql_hash"] diff --git a/backend/app/ledger/changes.py b/backend/app/ledger/changes.py new file mode 100644 index 00000000..a7928206 --- /dev/null +++ b/backend/app/ledger/changes.py @@ -0,0 +1,358 @@ +"""受限的字段变更服务(K03):一批字段操作打在**原图的深拷贝**上,交回新图和这次到底改了什么。 + +一条操作只说三件事:op(set / remove)、metric_id(口径卡上的稳定身份)、path(白名单里的字段路径)。指标身份、 +证据归属、治理归属、任意路径和按数组位置定位都不在能改的范围内(4.2)。改在深拷贝上做:没提到的字段、别的指标、 +别人加的扩展字段和其他节点原样带着走——不重建一份定义,也不做通用 JSON Patch。 + +白名单(FIELDS)覆盖当前指标上真有的业务字段和 definition 里给人看的那几项。**明确不能改**的写在 FORBIDDEN 里, +落进这里会得到一句具体的话,而不是笼统的「不认识这个字段」:id/kind/rule/assessment/external/params/contract(身份、 +指标类型和取值契约)、definition.citations(证据归属)、definition.owner / definition.effective_from(治理归属)。 + +四种写法的语义(4.2 要求各自不同且可测): + +| 写法 | 语义 | +| --- | --- | +| 省略 | 这条操作没提这个字段(整批都没提)就是**不动**它;反过来,set 省略 value 是错的(不知道要设成什么) | +| set + 值 | 把这个字段设成这个值 | +| set + ''(数组是 []) | 字段在、值是明确的空值——「声明成空」,和 remove 的「没声明」不是一回事 | +| set + null | 拒(operation_value):「清空」有 remove、「声明为空」有 '',null 只能是这两者之一,不替客户端猜 | +| remove | 把字段从指标里删掉,回到「没声明」。不接受 value | + +`definition` 整个对象不在(没这个键,或者就是 null)时:`set /definition/text|scope|exclusions` 会把它建出来, +`remove` 是同一条的「本来就没有」——无变化,不是路径非法。键在、但不是对象(被人写成了字符串或数组)照旧拒: +数据坏了就说清楚,不替人猜,也不把原来的值丢掉。 + +数组字段(同义词、维度、过滤条件、不包含)按**整份设置**处理,没有按元素的写法,也没有按位置定位的路径。 +一批操作要么全部成功(落成一个新版本),要么一条都不落:先在原图的深拷贝上把整批跑完,中途任何一条不合规、 +或者指标指不到,整批都不写(4.2)。整批跑完发现内容其实没变(比如先设后删),也不落版本。 + +变更分类(classification)按字段本身的类别算,见 FIELDS 的 kind:只改了展示类字段时报 display,动了定义类字段 +报 definition。**分类不代表可以跳过验证**:图是唯一真相,口径卡的内容一变,图的执行指纹就变,旧试跑与旧验证 +一律保守失效(4.8)——分类只是给页面说清「这次动的是哪一类」,回执里另给定义指纹的前后值(definition_hash) +作准。 + +**业务字段怎么落到 SQL 上(K04)。** `time_role`(统计时间口径)和 `refund_rule`(退款处理)是受控的业务字段: +它们同时在**定义**(指标里声明)和**实现**(取数节点上的受控绑定,ledger/bindings)里。一次变更里两边一起改: +能按受控模板确定性展开的,就在同一个事务里把取数节点的 args.sql 和 binding 一起改掉(synced);无绑定、映射不 +支持、SQL 被手工改过、同一条 SQL 上的指标说法打架的,**定义照常保存、SQL 一个字不动**,回执里照实报 +needs_update / unsupported + 原因 + 影响对象 + 该做什么。执行期绝不按业务语义重推(A09)。 +""" +from __future__ import annotations + +import copy +from collections.abc import Mapping, Sequence +from dataclasses import dataclass +from typing import Any + +from app.ledger import bindings +from app.ledger.repository import GraphBackedCaliberRepository, MetricGone + +#: 一次请求最多几条操作:再多不是「改一处」该有的样子(要整份重写就走整份换指标那条路) +MAX_OPERATIONS = 50 + +#: 拒绝的机器码(接口一律回 422) +OPERATION_INVALID = "operation_invalid" # op 不认识、一批是空的、太多条 +OPERATION_PATH = "operation_path" # 路径不在白名单、按数组位置定位、明确不能改的那几项 +OPERATION_VALUE = "operation_value" # 值不对:类型不符、null、set 没有 value、remove 带了 value +OPERATION_METRIC = "operation_metric" # 卡上没有这个 metric_id + +class ChangeRefused(Exception): + """这次变更不合规(接口回 422):code 是机器码,operation 是第几条(从 0 数),path 是那一条的字段路径。""" + + def __init__(self, message: str, *, code: str = OPERATION_INVALID, operation: int | None = None, + path: str | None = None) -> None: + super().__init__(message) + self.message = message + self.code = code + self.operation = operation + self.path = path + + +@dataclass(frozen=True) +class Field: + """白名单里的一个字段:kind 决定它算展示还是定义(见模块说明),value_type 是值类型,nonempty 是「写了就不能空」。""" + + kind: str + value_type: str + label: str + nonempty: bool = False + #: 值类型是 choice 时的允许值(业务字段的取值域,见 ledger/bindings.FIELDS) + choices: tuple[str, ...] = () + + +#: 能按字段改的路径。定义类的判定和 data/caliber_identity.SEMANTIC_FIELDS 对齐:语义字段算定义,其余(同义词)算展示。 +FIELDS: dict[str, Field] = { + "/name": Field("definition", "text", "指标名称", nonempty=True), + "/synonyms": Field("display", "texts", "同义词"), + "/unit": Field("definition", "text", "单位"), + "/decimals": Field("definition", "int", "小数位"), + "/format": Field("definition", "text", "展示格式"), + "/expression": Field("definition", "text", "取值表达式", nonempty=True), + "/grain": Field("definition", "text", "粒度"), + "/time_field": Field("definition", "text", "时间字段"), + "/numerator": Field("definition", "text", "分子"), + "/denominator": Field("definition", "text", "分母"), + "/dimensions": Field("definition", "texts", "维度"), + "/filters": Field("definition", "texts", "过滤条件"), + "/definition/text": Field("definition", "text", "口径说明"), + "/definition/scope": Field("definition", "text", "适用范围"), + "/definition/exclusions": Field("definition", "texts", "不包含"), +} + +#: 业务字段(K04):统计时间口径、退款处理。词汇表和允许值在 ledger/bindings(读接口的能力描述共用同一份), +#: 这里只是把它们接进按字段改的白名单。它们进了 data/caliber_identity.SEMANTIC_FIELDS:改了定义身份就变, +#: 绑定同步状态跟着重判(见 ledger/bindings 与 docs 的 4.5)。 +FIELDS.update({f"/{name}": Field("definition", "choice", spec.label, choices=tuple(spec.values())) + for name, spec in bindings.FIELDS.items()}) + +#: 明确不能改的路径:身份、指标类型、取值契约、证据归属和治理归属(4.2)。写清楚为什么,不混进「不认识这个字段」。 +FORBIDDEN: dict[str, str] = { + "/id": "指标身份不能改:改名、重排都不换 ID,删掉之后也不把这个 ID 分给别的业务指标(4.1)", + "/kind": "指标类型(算式 / 规则 / 评估 / 外部常量)决定读哪一份输入,不按字段改", + "/rule": "规则型指标的规则要整份换,不按字段改", + "/assessment": "评估型指标的评分协议要整份换,不按字段改", + "/external": "外部常量自带来源和生效时间,不按字段改", + "/params": "取值参数要整份换,不按字段改", + "/contract": "取值契约是结构声明(MetricContract):改它要过校验,不按字段改", + "/open_questions": "未决问题走「回答并移除」那条路(PATCH 的 resolved)", + "/definition/citations": "引用原文是证据归属:只能由核对过证据的流程写,字段操作改不了它", + "/definition/owner": "负责人是治理信息,不在字段变更的范围内", + "/definition/effective_from": "生效日期是治理信息,不在字段变更的范围内", +} + +#: 路径上「没有这个键」的标记(和值就是 None 分开:设成 null 是被拒的,读到的 None 只可能来自数据本身) +_MISSING = object() + + +@dataclass(frozen=True) +class Change: + """一次字段变更的结果:新图(原图的深拷贝 + 这几处)、改了什么、算哪一类、定义指纹前后值、绑定的处置。 + + applied 是「内容真的变了」:整批最后和前一份内容一致(先设后删)时是 False,调用方据此不落新版本。 + binding 是 ledger/bindings 的判定:定义和取数节点上的受控绑定对不对得上、能不能同步、影响哪些对象; + synced 表示这一次在同一事务里把取数 SQL 也按受控模板改过来了。 + """ + + graph: dict[str, Any] + card: str + applied: bool + classification: str + metrics: tuple[str, ...] + operations: tuple[dict[str, Any], ...] + definition_hash: tuple[str, str] + binding: bindings.Report + synced: bool = False + + +def field_of(path: str, *, operation: int | None = None) -> Field: + """路径 → 白名单里的字段;不在白名单、按数组位置定、或者属于明确不能改的那几项时 ChangeRefused。""" + text = str(path or "") + if not text.startswith("/"): + raise ChangeRefused(f"字段路径要以 / 开头(现在是「{text}」)", code=OPERATION_PATH, operation=operation, path=text) + if text in FORBIDDEN: + raise ChangeRefused(f"{text} 不能按字段改:{FORBIDDEN[text]}", code=OPERATION_PATH, operation=operation, path=text) + segments = [segment for segment in text.split("/") if segment] + if any(segment.isdigit() for segment in segments): + raise ChangeRefused(f"不能按数组位置定位({text}):数组字段整份设置,指标身份用 metric_id,不用位置", + code=OPERATION_PATH, operation=operation, path=text) + field = FIELDS.get(text) + if field is None: + allowed = "、".join(sorted(FIELDS)) + raise ChangeRefused(f"不能改这个字段:{text}。能按字段改的是:{allowed}", + code=OPERATION_PATH, operation=operation, path=text) + return field + + +def _read(index: int, raw: Any) -> tuple[str, str, str, Any]: + """读一条操作并校验形状:(op, metric_id, path, value)。「有没有写 value」在这一步就判完(省略和 null 是两件事)。""" + if not isinstance(raw, Mapping): + raise ChangeRefused(f"第 {index + 1} 条操作不是一个对象", operation=index) + op = str(raw.get("op") or "").strip() + if op not in ("set", "remove"): + raise ChangeRefused(f"不认识的 op:{op or '(空)'}。只支持 set(按字段设值)和 remove(删掉这个字段)", + operation=index) + metric_id = raw.get("metric_id") + if not isinstance(metric_id, str) or not metric_id.strip(): + raise ChangeRefused(f"第 {index + 1} 条操作缺少 metric_id(指标在口径里的稳定身份)", operation=index) + path = raw.get("path") + if not isinstance(path, str) or not path.strip(): + raise ChangeRefused(f"第 {index + 1} 条操作缺少 path(字段路径)", operation=index) + has_value = "value" in raw + if op == "remove" and has_value: + raise ChangeRefused(f"remove 不接受 value({path.strip()}):要「声明成空」用 set + ''(数组用 [])," + "要「没声明」才用 remove", code=OPERATION_VALUE, operation=index, path=path.strip()) + if op == "set" and not has_value: + raise ChangeRefused(f"set 要带 value({path.strip()}):字符串写 '',数组写 [],清空字段用 remove", + code=OPERATION_VALUE, operation=index, path=path.strip()) + return op, metric_id.strip(), path.strip(), raw.get("value") + + +def _checked(index: int, path: str, field: Field, value: Any) -> Any: + """按字段的值类型校验这个值。null 单独拒:它是「清空」还是「声明为空」说不清,不替客户端猜。""" + def refuse(message: str) -> None: + raise ChangeRefused(message, code=OPERATION_VALUE, operation=index, path=path) + + if value is None: + refuse(f"{path} 不能设成 null:「清空」用 remove、「声明成空」用 ''(数组用 []),两种都不是就写具体值") + if field.value_type == "choice": + if not isinstance(value, str): + refuse(f"{field.label}({path})要是字符串") + if value not in field.choices: + spec = bindings.FIELDS.get(path[1:]) + allowed = "、".join(f"{choice}({spec.label_of(choice) if spec else choice})" for choice in field.choices) + refuse(f"{field.label}({path})只能是:{allowed}") + return value + if field.value_type == "text": + if not isinstance(value, str): + refuse(f"{field.label}({path})要是字符串") + if field.nonempty and not value.strip(): + refuse(f"{field.label}({path})不能是空串") + return value + if field.value_type == "texts": + if not isinstance(value, list) or any(not isinstance(item, str) or not item.strip() for item in value): + refuse(f"{field.label}({path})要是字符串数组,而且是整份设置(不能按位置改其中一项)") + return copy.deepcopy(value) + if isinstance(value, bool) or not isinstance(value, int): + refuse(f"{field.label}({path})要是整数") + if value < 0: + refuse(f"{field.label}({path})不能是负数") + return value + + +def _container(metric: dict[str, Any], path: str, *, index: int, op: str) -> tuple[dict[str, Any], str]: + """值所在的容器和键名:/definition/text 装在 metric["definition"] 里,别的都在指标自己身上。 + + 装子字段的对象还没建(没这个键,或者就是 null)时:set 顺手建一个——字段本来就该装在里面(好几条指标就只有 + definition 之外的内容);remove 当「本来就没有这个字段」处理,是无变化,不是路径非法,也不往指标上补一个空对象。 + 键在、但不是对象(比如被人写成了字符串或数组)才拒:那是数据坏了,不替人猜该改成什么,更不把原来的值丢掉。 + """ + head, _, tail = path[1:].partition("/") + if not tail: + return metric, head + block = metric.get(head) + if block is None: + if op == "remove": + return {}, tail + block = metric[head] = {} + return block, tail + if not isinstance(block, dict): + raise ChangeRefused(f"指标上的 {head} 不是对象,不能按字段改它({path})", + code=OPERATION_PATH, operation=index, path=path) + return block, tail + + +def _same(before: Any, after: Any) -> bool: + if before is _MISSING or after is _MISSING: + return before is _MISSING and after is _MISSING + return bool(before == after) + + +def apply_operations(graph: Mapping[str, Any] | None, *, card_id: str, + operations: Sequence[Mapping[str, Any]]) -> Change: + """把整批字段操作打到原图的深拷贝上,交回新图和这次改了什么。 + + 整批原子:所有操作都先在拷贝上跑,任何一条不合规、或者指标指不到就 ChangeRefused,图一个字节都不动(4.2)。 + 同一条指标上的多条操作按给的顺序依次生效(后面的看得见前面的结果)。 + """ + repo = GraphBackedCaliberRepository(graph, card_id=card_id) + if len(operations) > MAX_OPERATIONS: + raise ChangeRefused(f"一次最多改 {MAX_OPERATIONS} 条:再多请走整份换指标那条路") + if not operations: + raise ChangeRefused("operations 是空的:要改哪个字段就写哪几条") + + before_hash = repo.definition_hash() + working: dict[str, dict[str, Any]] = {} + kinds: set[str] = set() + report: list[dict[str, Any]] = [] + for index, raw in enumerate(operations): + op, metric_id, path, value = _read(index, raw) + field = field_of(path, operation=index) + if metric_id not in working: + try: + working[metric_id] = repo.metric(metric_id) + except MetricGone: + raise ChangeRefused( + f"这张口径卡上没有指标「{metric_id}」:首版不支持用字段操作新增或删除指标(改名、重排都不换 ID)", + code=OPERATION_METRIC, operation=index, path=path) from None + container, key = _container(working[metric_id], path, index=index, op=op) + was = container.get(key, _MISSING) + if op == "remove": + container.pop(key, None) + else: + container[key] = _checked(index, path, field, value) + now = container.get(key, _MISSING) + moved = not _same(was, now) + if moved: + kinds.add(field.kind) + report.append({"op": op, "metric_id": metric_id, "path": path, "changed": moved}) + + changed = {metric_id: metric for metric_id, metric in working.items() if metric != repo.metric(metric_id)} + if not changed: + # 内容没变:交回原图的一份深拷贝(调用方照常走保存,save_graph 认出没变就不新增版本) + return Change(graph=repo.graph_copy(), card=repo.card_id, + applied=False, classification="none", metrics=(), operations=tuple(report), + definition_hash=(before_hash, before_hash), + binding=bindings.analyze(graph or {}, repo.card_id)) + new_graph = repo.replace_metrics(changed) + final, binding_report, synced = _sync_bindings(new_graph, repo.card_id) + after = GraphBackedCaliberRepository(final, card_id=repo.card_id) + return Change(graph=final, card=repo.card_id, applied=True, + classification="definition" if "definition" in kinds else "display", + metrics=tuple(metric_id for metric_id in repo.ids() if metric_id in changed), + operations=tuple(report), definition_hash=(before_hash, after.definition_hash()), + binding=binding_report, synced=synced) + + +def _sync_bindings(graph: dict[str, Any], card_id: str) -> tuple[dict[str, Any], bindings.Report, bool]: + """定义改完之后,取数节点上的受控绑定跟着改(K04,4.5):能确定性同步的把它一起改掉,改不了的原样留着。 + + 只改这几处:取数节点 args.sql(受控模板按新业务值展开)和 binding 的 values / rendered_hash / fingerprint。 + 有一条同步不了就**一条也不改**(定义照常保存,读的时候照实说 needs_update / unsupported + 原因和影响对象): + 一半改一半不改比都不改更糟——那才是「旧 SQL 的结果冒充新定义」。执行期不重推任何业务语义(A09)。 + """ + planned = bindings.plan(graph, card_id) + if not planned.configs: + return graph, planned, False + synced = GraphBackedCaliberRepository(graph, card_id=card_id).replace_node_configs(planned.configs) + return synced, bindings.analyze(synced, card_id), True + + +def summary(change: Change, *, applied: bool, revision: int | None) -> dict[str, Any]: + """给接口的变更回执(K03 的「变更分类、影响摘要、绑定状态、任务引用」,K04 接上真实的绑定状态)。 + + 只说这次真发生了什么:定义指纹前后的值、这次动到的指标、旧验证怎么失效、取数 SQL 同步到哪一步。绑定状态 + 来自 ledger/bindings 的实际判定(aligned / needs_update / unsupported / unbound),**不再恒为 unknown,也不 + 再把「改过定义」说成对齐**;aligned 只说定义和取数实现同步,不等于业务验证通过,也不改质量结论。验证记录 + K05 已经落库(caliber_validation_records,读法见 app/ledger/validation 与 + GET /api/ledger/drafts/{id}/validations):哪条记录还算覆盖当前定义/绑定、有没有独立期望、有没有认证审阅, + 都在那边算——所以这里的「下一步」仍是一句动作,不编一个任务号。 + """ + before, after = change.definition_hash + metrics = list(change.metrics) if applied else [] + if change.synced: + binding_reason = ("取数 SQL 已按受控模板在同一次变更里改过来:定义和实现是同步的" + "(aligned 只说明这两边对得上,不等于业务验证通过)") + else: + binding_reason = change.binding.reason + binding = {**change.binding.as_dict(), "reason": binding_reason, "synced": change.synced} + return { + "applied": applied, + "classification": change.classification if applied else "none", + "card": change.card, + "metrics": metrics, + "operations": [dict(item) for item in change.operations], + "revision": revision, + "definition_hash": {"before": before, "after": after, "changed": before != after}, + "validation": { + "invalidated": applied, "scope": "card", "metrics": metrics, + "reason": "口径卡的内容变了(图的执行指纹跟着变):旧的试运行记录和验证不再算覆盖这一版," + "按卡片保守失效(4.8)" + if applied else "这次操作没有改动任何内容:图没换版本,原来的验证仍然对着这一版", + "next": "重新试运行,按新定义取一次独立样例" if applied else "不用重新试运行", + }, + "binding": binding, + } + + +__all__ = ["FIELDS", "FORBIDDEN", "MAX_OPERATIONS", "OPERATION_INVALID", "OPERATION_METRIC", "OPERATION_PATH", + "OPERATION_VALUE", "Change", "ChangeRefused", "Field", "apply_operations", "field_of", "summary"] diff --git a/backend/app/ledger/closure.py b/backend/app/ledger/closure.py new file mode 100644 index 00000000..1a222b79 --- /dev/null +++ b/backend/app/ledger/closure.py @@ -0,0 +1,631 @@ +"""K08 的依赖闭包:一张**已经读好的**口径卡「这次要算哪些指标、要执行哪几条查询、要哪些入口参数」(S1 解析,S2 接线)。 + +**这一层是纯函数。** 进的是图(dict)+ 定位(workflow_id / version / card_id)+ 选择(可选 metric_ids,或显式 +whole_card=True),出的是一个不可变的 DependencyClosure:不读库、不写库、不调模型、不 import 运行路径。S2 已经把它接进 +``derive.load_pinned`` / ``derive.select_pinned`` / ``derive.caliber_block`` 与 ``compose.check_inputs`` / +``compose.instantiate``:给了选择就按这份闭包决定拷哪些取数节点、要哪些入口字段、口径卡上记哪几个指标;不给选择还是整卡 +(闭包附在 Pinned 上供调用方读身份与依赖)。``engine/nodes/metrics`` 那边「只算选中的那几个指标」的接缝是 +``effective_metrics``(按口径卡上记的选择筛定义、保持源卡相对顺序),见文末「S2 接线到了哪」。 + +**为什么要单独一份。** 现在「这张卡要读哪些取数节点」只有整卡一个粒度(look/calibers.card_inputs、 +derive.load_pinned、bindings 的指标→节点映射都按整卡算)。K08 要的是同一份依赖模型同时供影响分析、验证范围和执行 +计划用,而且要支持**选一部分指标**:选 A 时 B 独有且无依赖的查询和参数不进这次范围,共享的那条 SQL 保留、并显式声明 +它还在算未选中的指标(不做投影——那要发布阶段拆模板或有验证过的投影能力)。 + +**身份**(§4.1、§4.6)。query_id 是**逻辑**查询身份:节点上声明了 ``data.config.query_id`` 就用它(别名,改名、 +换图都不变),否则由 ``workflow_id + node_id`` 定。它**不含版本**——同一版图换个版本号,查询身份不变,版本另记在 +``source`` 上。每个查询记录里同时留着真实出处 ``source = {workflow_id, version, node_id}``:别名不是源身份,换名的 +副本(caliber_from.nodes 那种映射)认的是本图里真正执行的那个节点。**两条内容一样的 SQL 不合并**——不拿 SQL 内容哈希 +当身份,两个节点就是两条查询(哪怕它们字节相同)。 + +**选择**。不给 metric_ids 也不给 whole_card 时,缺省保持整卡(现在各入口的行为);显式给 metric_ids 就是按源卡顺序 +归一的显式选择(调用方传的顺序、重复项都不影响结果)。指标不认识、取数式读不出来 / 引用不存在的节点 / 一个指标谁也 +不依赖、查询没有可读 SQL、SQL 引用未声明的参数或认不出的写法、绑定对不上——一律进 ``unresolved``,``require()`` +抛错。**绝不因为解析不了就静默退回整卡**;只有显式(或缺省)的整卡模式才产出整卡范围的闭包。 + +**绑定判定只看这次要执行的节点。** ``bindings.analyze`` 收的是**选中的指标**:未选中的指标独有节点上的问题根本不进 +这次范围(反例「B 独有错误导致 A 失败」);未选中的指标和 A 共享同一条 SQL 时,这条 SQL 仍按 A 的说法判、并如实由 +``computes_unselected`` 声明它还在算谁(B 的说法不牵连 A 的结论;B 的数也不交回)。 + +**复用而不是另起一套**。指标的取数式读的是 ``engine.metric_spec.metric_expressions``;参数(槽位、未声明、认不出 +的写法)读的是 ``ledger.params``;卡内容指纹读的是 ``data.caliber_identity.card_hash_of``;「哪个取数节点被哪个指标 +读」和「定义 vs 绑定对不对得上」读的是 ``ledger.bindings``(``_readers`` / ``analyze``)。这里只把结果收成闭包, +不另写第三份指标读数算法。``derive.entry_fields`` 也直接复用。 + +**两个哈希分工**(区别是有意的,测试锁住): + +- ``selection_hash``:本次**选择**的身份——resolver_version、source(workflow/version/card)、模式、选中指标、查询 + 身份、必需入口字段。**不含绑定指纹**:换参数值、定义与 SQL 一起同步到新版本之后,只要选的是同一批指标、同一批 + 查询,这次选择的身份不变。 +- ``closure_hash``:整份**闭包**的身份——在 selection 之上再算上整卡指纹、排除的查询、入口字段、每条查询的明细 + (含 SQL 哈希与**绑定指纹**)、跨指标契约、未决项、图 defaults 与卡的 on_missing。绑定一变,这个哈希就变。 + +resolver_version 两个都进(解析算法变了,两个身份都得变)。 + +**S2 接线到了哪、还剩什么**(照实说): + +- **已接**:`derive.load_pinned` / `derive.select_pinned` 按这份闭包裁取数节点、入口字段与绑定判定的范围; + `derive.caliber_block` 把选择记进口径卡的 `caliber_from.metrics`(按源卡顺序)、改名映射只列保留的查询; + `compose.check_inputs` / `instantiate` 按选择判参数与拷节点。未决依赖一律照实拒(`derive.SELECTION`),不静默 + 退回整卡。闭包里的 `required_entry_fields`、`entry_fields`、`on_missing`、`defaults` 就是它们各自要的那几样。 +- **查询的认法**:这一层认「被指标读到的调用工具节点」(`bindings._readers`);`look/calibers.card_inputs` 那一支 + (给模型看的口径目录、蓝图复用)另要求工具名以 `QUERY_PREFIX` 开头、行号是 0,两侧各按自己的门槛收,没有合并成一 + 条(改它的行为不在这一片)。 +- **转抄卡(`caliber_from`)**:这里报 `card_chained`——本图里没有自己的定义。要按固定那一版的指标解析,得由调用方把 + 钉住那一版、已按 `caliber_from.nodes` 改名映射改写过的指标传进来:派生路径本来只认源头卡,没有抽这层适配。 +- **共享 SQL 不做投影(S3)**:`Query.computes_unselected` 只是声明「这条 SQL 还在算谁」。要真不执行未选中指标,得在 + 发布阶段把模板拆开,或有验证过的投影能力;这一层明确不做投影,共享 SQL 原样保留。 +- **运行时只算选中的几个指标**:`effective_metrics` / `selection_index` 是那一份统一的人读接口(按卡上记的选择筛定义、 + 保持源卡相对顺序);引擎那一侧(`engine/nodes/metrics`)按口径卡上的 `caliber_from.metrics` 读它,`nodes.<卡>.metrics[i]` + 的下标也按它算——K08 的另一半接的就是这一份。 +- **S4(影响分析 / 验证范围)已接**:`Closure.summary()` 是这一份闭包的无 SQL 摘要(身份、这次算哪些指标、要执行哪几条 + 查询与共享声明、必需入口字段、绑定指纹),look 的选用选项(`Option.selectable_metrics` / `unavailable_metrics` / + `default_closure`)与口径描述(`ledger/descriptor` 的 `closure` / `selectable_metrics` / `computes_unselected`)都读它; + 按指标判能不能选的是 `look/calibers.metric_options`(闭包 + 同一份「输入能不能复用」的判定,不另写依赖解析)。 +- **S5 / S6**:`queries`(`query_id`/`node_id`/`source`/`sql_hash`)是执行与证据要记的身份,`sql_hash` 只记事实、不当身份、 + 不拿它合并节点;`contract_dependencies` 只列了能确定性读出来的两处(`ratio`、`report_contract`),执行侧怎么保住跨指标 + 约定(比例契约的分子分母同源、出具契约点名的指标)还没定。 +""" +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field +from typing import Any + +from app.apps.tree import node_map +from app.ledger import bindings, params +from app.ledger.derive import entry_fields as graph_entry_fields + +#: 解析算法版本:进 selection_hash 与 closure_hash(换解析规则就是换身份) +RESOLVER_VERSION = "closure/1" + +#: 选择模式(§4.6) +WHOLE_CARD = "whole_card" +EXPLICIT = "explicit" + +#: 未决项(unresolved)的机器码 +CARD_CHAINED = "card_chained" # 这张卡本身是转抄别处的(caliber_from):本图里没有定义可解析 +CARD_EMPTY = "card_has_no_metrics" # 整卡模式,可这张卡一个指标也没有 +CONFLICTING_SELECTION = "conflicting_selection" # whole_card 与 metric_ids 同时给了 +EMPTY_SELECTION = "empty_selection" # 显式给了空选择([]):不静默当整卡 +METRIC_UNKNOWN = "metric_unknown" # 点名的指标不在这张卡上 +EXPRESSION_UNREADABLE = "expression_unreadable" # 指标的取数式读不出来(kind 不认识、式子缺失) +NO_QUERY = "no_query_dependency" # 指标一个查库节点也不依赖 +UNKNOWN_NODE = "unknown_node" # 式子引用了图里不存在的节点 +QUERY_NO_SQL = "query_sql_missing" # 取数节点没有可读的 SQL +UNDECLARED_PARAMETER = "undeclared_parameter" # SQL 引用了入口没声明的参数(params.UNDECLARED) +UNSUPPORTED_PARAMETER = "unsupported_parameter" # SQL 里的参数认不出写法(params.UNSUPPORTED) +DUPLICATE_QUERY_ID = "duplicate_query_id" # 两条查询用了同一个逻辑身份:谁是它说不清 +BINDING_UNRESOLVED = "binding_unresolved" # 定义和取数节点上的受控绑定对不上(K04) +DUPLICATE_METRIC_ID = "duplicate_metric_id" # 同一张卡上两个指标用了同一个 id:谁是它说不清 + +CODES = (CARD_CHAINED, CARD_EMPTY, CONFLICTING_SELECTION, EMPTY_SELECTION, METRIC_UNKNOWN, EXPRESSION_UNREADABLE, + NO_QUERY, UNKNOWN_NODE, QUERY_NO_SQL, UNDECLARED_PARAMETER, UNSUPPORTED_PARAMETER, DUPLICATE_QUERY_ID, + DUPLICATE_METRIC_ID, BINDING_UNRESOLVED) + + +class ClosureRefused(ValueError): + """闭合解析的**输入本身**不可用(图不是图、卡不在、卡不是口径卡、版本不是整数):调用方先修正输入。 + + 数据层面的问题(指标不认识、式子读不出来、参数没声明、绑定对不上)不走这里,进 Closure.unresolved。""" + + +class UnresolvedClosure(Exception): + """require() 时闭包里还有没解决的依赖:problems 是 Closure.unresolved 的原样一份。""" + + def __init__(self, problems: Sequence[Mapping[str, Any]]) -> None: + self.problems = tuple(dict(p) for p in problems) + super().__init__(";".join(str(p.get("message") or p.get("code")) for p in self.problems)) + + +@dataclass(frozen=True) +class Query: + """一条逻辑查询:这次要执行的一条取数。query_id 是逻辑身份,node_id / source 是它在本图里的真实出处。""" + + query_id: str + node_id: str + tool: str + #: 真实出处:{workflow_id, version, node_id}(别名不当源身份,版本另记) + source: dict[str, Any] + #: 读这条查询的**选中**指标(按源卡顺序) + metric_ids: tuple[str, ...] + #: 没选中、但这条 SQL 照样在算的卡上指标(共享 SQL 保留时如实声明,不做投影) + computes_unselected: tuple[str, ...] + #: 这条 SQL 用到的入口字段名(按入口声明顺序) + required_entry_fields: tuple[str, ...] + #: 节点配置里那条 SQL 的内容哈希(记事实,不当身份、不拿它合并节点) + sql_hash: str + #: 这条查询上受控绑定的指纹(没有声明业务字段、或没有绑定时空串) + binding_fingerprint: str = "" + + def as_dict(self) -> dict[str, Any]: + return {"query_id": self.query_id, "node_id": self.node_id, "tool": self.tool, "source": dict(self.source), + "metric_ids": list(self.metric_ids), "computes_unselected": list(self.computes_unselected), + "required_entry_fields": list(self.required_entry_fields), "sql_hash": self.sql_hash, + "binding_fingerprint": self.binding_fingerprint} + + +@dataclass(frozen=True) +class Closure: + """一张口径卡(可选一部分指标)的依赖闭包。字段见模块说明与 §4.6 的最小集合。""" + + source: dict[str, Any] + mode: str + whole_card: bool + #: 卡上所有指标 id(按源卡顺序);原始整卡身份 + card_metric_ids: tuple[str, ...] + #: 这次要算的指标 id(按源卡顺序归一) + metric_ids: tuple[str, ...] + #: 这次要执行的查询身份(按源卡顺序) + query_ids: tuple[str, ...] + #: 卡上有、这次不执行的查询身份(B 独有) + excluded_query_ids: tuple[str, ...] + queries: tuple[Query, ...] + #: 这次真正要用到的入口字段(按入口声明顺序) + required_entry_fields: tuple[dict[str, Any], ...] + #: 图里入口声明的全部字段(照抄,保真交给下游) + entry_fields: tuple[dict[str, Any], ...] + #: query_id → 绑定指纹 + binding_fingerprints: dict[str, str] + #: 这次选择必须一起保留的跨指标约定(见 _contract_dependencies) + contract_dependencies: tuple[dict[str, Any], ...] + #: 没解决的依赖:[{code, message, metric_id?, node_id?, query_id?}];非空时 require() 抛错 + unresolved: tuple[dict[str, Any], ...] + resolver_version: str + source_card_hash: str + selection_hash: str + closure_hash: str + #: 卡的「缺输入时」与图级 defaults:这次选择照样要带上(§4.6 保留全局必要约束) + on_missing: Any = None + defaults: dict[str, Any] = field(default_factory=dict) + + @property + def ok(self) -> bool: + return not self.unresolved + + def require(self) -> "Closure": + """闭包可用时交回自己,有未决项时抛 UnresolvedClosure。调用方拿它当「能不能按这份闭包执行」的闸。""" + if self.unresolved: + raise UnresolvedClosure(self.unresolved) + return self + + def metric_query_ids(self, metric_id: str) -> list[str]: + """某个指标这次要执行的查询身份(按源卡顺序)。""" + return [q.query_id for q in self.queries if str(metric_id) in q.metric_ids] + + def as_dict(self) -> dict[str, Any]: + return { + "source": dict(self.source), "mode": self.mode, "whole_card": self.whole_card, + "card_metric_ids": list(self.card_metric_ids), "metric_ids": list(self.metric_ids), + "query_ids": list(self.query_ids), "excluded_query_ids": list(self.excluded_query_ids), + "queries": [q.as_dict() for q in self.queries], + "required_entry_fields": [dict(f) for f in self.required_entry_fields], + "entry_fields": [dict(f) for f in self.entry_fields], + "binding_fingerprints": dict(self.binding_fingerprints), + "contract_dependencies": [dict(d) for d in self.contract_dependencies], + "unresolved": [dict(p) for p in self.unresolved], "resolver_version": self.resolver_version, + "source_card_hash": self.source_card_hash, "selection_hash": self.selection_hash, + "closure_hash": self.closure_hash, "on_missing": self.on_missing, "defaults": dict(self.defaults), + } + + + def summary(self) -> dict[str, Any]: + """这份闭包的摘要(K08 S4):这次算哪些指标、要执行哪几条查询(query_id / 节点 / 工具 / 各自算谁 / 共享声明)、 + 必需入口字段、绑定指纹、跨指标约定与两份身份哈希。**没有 SQL 正文、没有参数值**——目录页、look 的选用选项 + (ledger/compose.Option)与口径描述(ledger/descriptor)读这一份;SQL 只在服务端实例化那一刻照抄。""" + return { + "mode": self.mode, "whole_card": self.whole_card, + "metric_ids": list(self.metric_ids), "card_metric_ids": list(self.card_metric_ids), + "query_ids": list(self.query_ids), "excluded_query_ids": list(self.excluded_query_ids), + "queries": [{"query_id": q.query_id, "node_id": q.node_id, "tool": q.tool, + "metric_ids": list(q.metric_ids), "computes_unselected": list(q.computes_unselected), + "required_entry_fields": list(q.required_entry_fields), + "sql_hash": q.sql_hash, "binding_fingerprint": q.binding_fingerprint} + for q in self.queries], + "required_entry_fields": [str(f.get("name")) for f in self.required_entry_fields], + "binding_fingerprints": dict(self.binding_fingerprints), + "contract_dependencies": [dict(d) for d in self.contract_dependencies], + "unresolved": [dict(p) for p in self.unresolved], + "selection_hash": self.selection_hash, "closure_hash": self.closure_hash, + "source_card_hash": self.source_card_hash, "resolver_version": self.resolver_version, + } + + +# ========================================================================== +# 这次算哪些指标:在源卡里的位置(运行时统一的一份人读接口) +# ========================================================================== + + +@dataclass(frozen=True) +class SelectionIndex: + """一次选择在源卡里的位置:要算哪些指标、各自在源卡第几个、选择里认不出的 id。 + + ``definitions`` 与 ``positions`` 一一对应,都按**源卡相对顺序**(不是调用方给的顺序)。整卡模式(selection 是 None) + 里就是卡上的全部定义原样(顺序、条目一个不动),``whole_card`` 为真、``unknown`` 为空。 + """ + + definitions: tuple[Any, ...] + positions: tuple[int, ...] + whole_card: bool + unknown: tuple[str, ...] + + @property + def metric_ids(self) -> tuple[str, ...]: + return tuple(str(d.get("id")) for d in self.definitions if isinstance(d, Mapping) and d.get("id")) + + def as_dict(self) -> dict[str, Any]: + return {"metric_ids": list(self.metric_ids), "positions": list(self.positions), + "whole_card": self.whole_card, "unknown": list(self.unknown)} + + +def selection_index(definitions: Iterable[Any], selection: Sequence[str] | None = None) -> SelectionIndex: + """一次选择在源卡里的位置:算哪些指标、各自的下标、选择里认不出的 id(取舍与顺序只由这一处算)。 + + - ``selection`` 是 None(或没给):整卡——原样交回全部定义(顺序与条目一个不动); + - 给了序列:只留 id 在里面的定义,**按源卡顺序**(调用方传的顺序、重复项都不影响结果);选择里这张卡上没有的 id 进 + ``unknown``(照实交回,既不静默当整卡,也不静默丢掉); + - 同一个 id 在卡上出现多次只取第一次(口径卡的 id 该唯一;这一层不替它去重之后算两遍)。 + + 运行时按口径卡上记的选择(``caliber_from.metrics``)读这一份:卡片顺序、认不出的 id 都按同一处判定。""" + defs = list(definitions or []) + if selection is None: + return SelectionIndex(tuple(defs), tuple(range(len(defs))), True, ()) + wanted = list(dict.fromkeys(str(m).strip() for m in selection if m is not None and str(m).strip())) + chosen = set(wanted) + kept: list[tuple[int, Any]] = [] + seen: set[str] = set() + for position, definition in enumerate(defs): + metric_id = str(definition.get("id") or "").strip() if isinstance(definition, Mapping) else "" + if metric_id and metric_id in chosen and metric_id not in seen: + seen.add(metric_id) + kept.append((position, definition)) + return SelectionIndex(tuple(d for _, d in kept), tuple(p for p, _ in kept), False, + tuple(m for m in wanted if m not in seen)) + + +def effective_metrics(definitions: Iterable[Any], selection: Sequence[str] | None = None) -> list[Any]: + """这次要算的指标定义(运行时统一的一份):selection 给了就按它筛,**保持源卡相对顺序**;没给就是整卡(原样)。 + + 实现在 ``selection_index`` 之上:位置与取舍只由那一处算。引擎按口径卡上记的选择读它,把「这张卡这次算哪几个指标」 + 统一到一处,别处不再各写一遍筛选与排序。""" + return list(selection_index(definitions, selection).definitions) + + +# ========================================================================== +# 身份与哈希 +# ========================================================================== + + +def query_id_of(workflow_id: str, node_id: str, config: Mapping[str, Any] | None = None) -> str: + """一条查询的逻辑身份:节点上声明了 ``config.query_id`` 就用它(别名),否则由 ``workflow_id:node_id`` 定。 + + **不含版本**:同一版图换个版本号,查询身份不变(版本记在 source 上,§4.6)。别名不是源身份——调用方要记出处时 + 仍看节点 id(Query.source)。""" + explicit = (config or {}).get("query_id") + if isinstance(explicit, str) and explicit.strip(): + return explicit.strip() + return f"{workflow_id}:{node_id}" + + +def _hash(payload: Any) -> str: + from app.core.artifact_store import canonical_json, content_hash + + return content_hash(canonical_json(payload)) + + +def _problem(code: str, message: str, **extra: Any) -> dict[str, Any]: + return {"code": code, "message": message, **{k: v for k, v in extra.items() if v not in (None, "")}} + + +def _config(node: Any) -> dict[str, Any]: + config = (node.get("data") or {}).get("config") if isinstance(node, Mapping) else None + return config if isinstance(config, dict) else {} + + +def _sql_of(config: Mapping[str, Any]) -> str | None: + args = config.get("args") + sql = args.get("sql") if isinstance(args, Mapping) else None + return sql if isinstance(sql, str) else None + + +def _names(fields: Sequence[Mapping[str, Any]]) -> list[str]: + return [str(f["name"]) for f in fields if f.get("name")] + + +# ========================================================================== +# 解析 +# ========================================================================== + + +def _metric_problems(nodes: Mapping[str, Mapping[str, Any]], metric: Mapping[str, Any]) -> tuple[list[str] | None, list[dict[str, Any]]]: + """一个指标的取数式读不读得出来、引用了图里不存在的节点没有。交回 (取数式, 未决项)。 + + 只做**诊断**(式子读不出来、引用了谁):真正的「指标→取数节点」映射一律走 bindings._readers(同一份读数算法), + 不在这里另写一遍。""" + from app.engine.expressions import ExpressionError, cell_parts, leaf_refs, parse_expression + from app.engine.metric_spec import metric_expressions + + metric_id = str(metric.get("id")) + paths = metric_expressions(metric) + if paths is None: + return None, [_problem(EXPRESSION_UNREADABLE, + f"指标「{metric_id}」的取数式读不出来(kind 不认识,或式子在当前类型下是空的):" + "解析不了依赖,不能按它执行", metric_id=metric_id)] + problems: list[dict[str, Any]] = [] + ghosts: list[str] = [] + for path in paths: + try: + tree, _, _ = parse_expression(path) + except ExpressionError as e: + problems.append(_problem(EXPRESSION_UNREADABLE, f"指标「{metric_id}」的取数式解析不了:{e}", + metric_id=metric_id)) + continue + for leaf in leaf_refs(tree): + parts = cell_parts(leaf) + if parts is None or not parts[0].startswith("nodes."): + continue + node_id = parts[0][len("nodes."):] + if node_id not in nodes and node_id not in ghosts: + ghosts.append(node_id) + for node_id in ghosts: + problems.append(_problem(UNKNOWN_NODE, f"指标「{metric_id}」的取数式引用了图里不存在的节点「{node_id}」:" + "先把它接上,别拿别的节点的数顶替", metric_id=metric_id, node_id=node_id)) + return list(paths), problems + + +def _contract_dependencies(graph: Mapping[str, Any], card_metric_ids: Sequence[str], selected: Sequence[str], + selected_metrics: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]: + """这次选择必须一起保留的**跨指标约定**(照实列,不在 S1 里改任何东西): + + - ``ratio``:选中指标声明的比例契约(分子、分母要来自同一条查询的那一行)——按列名记下来,交给 S2 决定怎么保; + - ``report_contract``:图里某个节点的 ``config.contract`` 点名了这张卡的指标(``metrics_from`` 那套约定的 + ``required``):选 A 时它可能还点着未选中的 B,如实记下「选了哪些、还剩哪些没选」。 + + 只认能确定性读出来的两处;别的跨指标关系(模型写的自然语言、没声明的约定)不在这里猜。""" + selected_set = set(selected) + card_set = set(card_metric_ids) + out: list[dict[str, Any]] = [] + for metric in selected_metrics: + contract = metric.get("contract") + ratio = contract.get("ratio") if isinstance(contract, Mapping) else None + if isinstance(ratio, Mapping) and str(ratio.get("numerator") or "").strip() \ + and str(ratio.get("denominator") or "").strip(): + out.append({"kind": "ratio", "metric_id": str(metric.get("id")), + "numerator": str(ratio["numerator"]).strip(), + "denominator": str(ratio["denominator"]).strip()}) + for node_id, node in node_map(graph).items(): + contract = (node.get("config") or {}).get("contract") + required = contract.get("required") if isinstance(contract, Mapping) else None + if not isinstance(required, (list, tuple)): + continue + named = [str(m) for m in required if str(m) in card_set] + if not named: + continue + out.append({"kind": "report_contract", "node_id": node_id, "metric_ids": named, + "unselected": [m for m in named if m not in selected_set]}) + return out + + +def duplicate_metric_ids(metrics: Sequence[Mapping[str, Any]]) -> list[str]: + """这张卡上重复出现的非空指标 id(按第一次出现的先后;重复几次只报一次)。 + + 同一张卡上每个指标 id 只能出现一次:重复就是谁是谁说不清——闭包按定义解析、运行时按指标集筛、下游按位置取 + ``nodes.<卡>.metrics[i]`` 会各算一份。判定只有这一处(closure.build 与 derive.load_pinned 都读它)。""" + seen: set[str] = set() + out: list[str] = [] + for metric in metrics: + metric_id = str(metric.get("id") or "") if isinstance(metric, Mapping) else "" + if not metric_id: + continue + if metric_id in seen and metric_id not in out: + out.append(metric_id) + seen.add(metric_id) + return out + + +def build(graph: Mapping[str, Any], workflow_id: str, version: int, card_id: str, *, + metric_ids: Sequence[str] | None = None, whole_card: bool = False) -> Closure: + """解析一张已读好的口径卡的依赖闭包(纯函数,无 IO / LLM,不改任何模块的行为)。 + + - ``metric_ids`` 不给(None)且 ``whole_card=False``:缺省保持整卡(和现在各入口一样); + - 给了 ``metric_ids``:显式选择,按**源卡顺序**归一(调用方传的顺序与重复项不影响结果); + - ``metric_ids=[]``:显式空选择 → unresolved(不静默当整卡); + - ``whole_card=True`` 与 ``metric_ids`` 同时给:unresolved(不按任何一边静默放宽); + - 同一张卡上两个指标用同一个非空 id:unresolved(``duplicate_metric_id``),哪一种模式都报——重复的 id 说不清算的是 + 哪一份,闭包按定义解析、运行时按指标集筛、下游按位置取 ``nodes.<卡>.metrics[i]`` 会各算一份(也不静默挑第一或最后)。 + + 输入本身不可用(图不是图、卡不在、卡不是口径卡、版本不是整数)抛 ClosureRefused;数据层面的问题进 unresolved。 + """ + if not isinstance(graph, Mapping): + raise ClosureRefused("依赖闭包要的是一张图(dict)") + if metric_ids is not None and (isinstance(metric_ids, (str, bytes)) or not isinstance(metric_ids, Sequence)): + raise ClosureRefused("metric_ids 要给一串指标 id(或 None 表示不指定选择)") + try: + version_no = int(version) + except (TypeError, ValueError): + raise ClosureRefused(f"口径版本要是整数:{version!r}") from None + workflow_id, card_id = str(workflow_id or ""), str(card_id or "") + + nodes = node_map(graph) + card_node = nodes.get(card_id) + if card_node is None: + raise ClosureRefused(f"图里没有节点「{card_id}」:定位不到要解析的口径卡") + if card_node.get("type") != "metrics": + raise ClosureRefused(f"「{card_id}」不是口径卡(metrics 节点):不能按口径算依赖") + + config = card_node.get("config") or {} + source = {"workflow_id": workflow_id, "version": version_no, "card_id": card_id} + unresolved: list[dict[str, Any]] = [] + + entry_fields = tuple(graph_entry_fields(graph)) + declared_fields = params.declared(entry_fields) + field_names = _names(entry_fields) + + chained = config.get("caliber_from") not in (None, "", {}) + if chained: + unresolved.append(_problem(CARD_CHAINED, + f"「{card_id}」是转抄别处口径的卡:本图里没有自己的定义," + "要按固定那一版的指标(式子已按改名映射改写)再解析", + node_id=card_id)) + metrics = [] if chained else [m for m in config.get("metrics") or [] + if isinstance(m, Mapping) and m.get("id")] + card_metric_ids = list(dict.fromkeys(str(m["id"]) for m in metrics)) + if duplicates := duplicate_metric_ids(metrics): + # 同一张卡上 id 重复:卡的指标身份本身坏了(闭包按定义解析、运行时按指标集筛、下游按位置取 metrics[i] 各算一份)。 + # 不是「某个指标的问题」,所以哪一种模式都照实报,也不静默取第一份或最后一份 + unresolved.append(_problem(DUPLICATE_METRIC_ID, + f"「{card_id}」上有指标 id 重复:{'、'.join(duplicates)}——同一张卡上每个指标 id " + "只能有一个,谁是它说不清,先改成不重的 id", metric_id=duplicates[0])) + + # ---- 选择:归一(按源卡顺序)------------------------------------------------ + if whole_card and metric_ids is not None: + # 两边都给了:照实报冲突,并按更窄的一边(点名的指标)走——绝不悄悄放大到整卡 + unresolved.append(_problem(CONFLICTING_SELECTION, + "whole_card 和 metric_ids 同时给了:要么点指标、要么整卡,不按哪一边静默放宽")) + mode = EXPLICIT + elif whole_card or metric_ids is None: + mode = WHOLE_CARD + else: + mode = EXPLICIT + if mode == WHOLE_CARD: + selected = list(card_metric_ids) + else: + wanted = list(dict.fromkeys(str(m) for m in metric_ids or [])) + if not wanted: + unresolved.append(_problem(EMPTY_SELECTION, "metric_ids 给的是空的:这次一个指标也不选(不静默当整卡)")) + selected = [] + else: + for metric_id in [m for m in wanted if m not in card_metric_ids]: + unresolved.append(_problem(METRIC_UNKNOWN, + f"「{card_id}」上没有指标「{metric_id}」:有 " + f"{'、'.join(card_metric_ids) or '(一个也没有)'}", metric_id=metric_id)) + chosen = set(wanted) & set(card_metric_ids) + selected = [mid for mid in card_metric_ids if mid in chosen] + selected_set = set(selected) + if mode == WHOLE_CARD and not card_metric_ids and not chained: + unresolved.append(_problem(CARD_EMPTY, f"「{card_id}」一个指标也没有:整卡模式下没有可执行的范围", + node_id=card_id)) + by_id: dict[str, dict[str, Any]] = {} + for metric in metrics: + by_id.setdefault(str(metric["id"]), metric) # id 重复时取第一份:和运行时按指标集筛的认法一致(重复本身已未决) + selected_metrics = [by_id[mid] for mid in selected if mid in by_id] + + # ---- 指标 → 取数节点:走 bindings 的读数算法(不另写一份)-------------------- + all_readers = bindings._readers(graph, metrics) + sel_readers = bindings._readers(graph, selected_metrics) + nodes_by_metric: dict[str, list[str]] = {} + for node_id, mids in all_readers.items(): + for metric_id in mids: + nodes_by_metric.setdefault(metric_id, []).append(node_id) + card_nodes_order = [node_id for node_id in nodes if node_id in all_readers] + retained_order = [node_id for node_id in nodes if node_id in sel_readers] + excluded_query_nodes = [node_id for node_id in card_nodes_order if node_id not in sel_readers] + + # ---- 选中指标自己的诊断(式子读不出来、引用不存在的节点、谁也不依赖)-------- + for metric in selected_metrics: + metric_id = str(metric["id"]) + paths, problems = _metric_problems(nodes, metric) + unresolved += problems + if paths and not problems and not nodes_by_metric.get(metric_id): + unresolved.append(_problem(NO_QUERY, f"指标「{metric_id}」的取数式没有引用任何查库的取数节点:" + "依赖解析不了,不能按它执行", metric_id=metric_id)) + + # ---- 定义 vs 绑定:只看这次真正要执行的那些节点(未选中指标的绑定问题不牵连 A)-- + report = bindings.analyze(graph, card_id, selected_metrics) + for state in report.nodes: + if state.status in (bindings.NEEDS_UPDATE, bindings.UNSUPPORTED): + unresolved.append(_problem(BINDING_UNRESOLVED, f"取数节点「{state.node_id}」:{state.reason}", + node_id=state.node_id)) + fingerprints = report.fingerprints + + # ---- 每条查询:身份、参数、绑定指纹、共享 SQL 还在算谁 ---------------------- + queries: list[Query] = [] + seen_query_ids: dict[str, str] = {} + used_anywhere: set[str] = set() + for node_id in retained_order: + cfg = nodes[node_id].get("config") or {} + query_id = query_id_of(workflow_id, node_id, cfg) + if query_id in seen_query_ids: + unresolved.append(_problem(DUPLICATE_QUERY_ID, + f"取数节点「{node_id}」和「{seen_query_ids[query_id]}」用了同一个逻辑身份" + f"「{query_id}」:谁是这条查询说不清,先改 name/query_id", + query_id=query_id, node_id=node_id)) + else: + seen_query_ids[query_id] = node_id + sql = _sql_of(cfg) + used: list[str] = [] + if sql is None or not sql.strip(): + unresolved.append(_problem(QUERY_NO_SQL, f"取数节点「{node_id}」没有可读的 SQL(args.sql):" + "这条查询执行不了", node_id=node_id, query_id=query_id)) + else: + for problem in params.check_template(sql, fields=declared_fields, values=None, node_id=node_id, + where=f"口径「{card_id}」的入口"): + unresolved.append(_problem(problem.code, problem.message, node_id=node_id, query_id=query_id)) + try: + used = list(dict.fromkeys(slot.field for slot in params.slots_of(sql))) + except params.ParameterRefused: + used = [] + required = [name for name in field_names if name in set(used) and name in declared_fields] + used_anywhere.update(required) + queries.append(Query( + query_id=query_id, node_id=node_id, tool=str(cfg.get("tool") or ""), + source={"workflow_id": workflow_id, "version": version_no, "node_id": node_id}, + metric_ids=tuple(mid for mid in card_metric_ids + if mid in selected_set and node_id in nodes_by_metric.get(mid, [])), + computes_unselected=tuple(mid for mid in card_metric_ids + if mid not in selected_set and node_id in nodes_by_metric.get(mid, [])), + required_entry_fields=tuple(required), + sql_hash=bindings.sql_hash(sql) if sql else "", + binding_fingerprint=str(fingerprints.get(node_id) or ""))) + + required_entry_fields = tuple(f for f in entry_fields if str(f.get("name")) in used_anywhere) + binding_fingerprints = {q.query_id: q.binding_fingerprint for q in queries if q.binding_fingerprint} + query_ids = [q.query_id for q in queries] + excluded_query_ids = [query_id_of(workflow_id, node_id, nodes[node_id].get("config") or {}) + for node_id in excluded_query_nodes] + + contract_dependencies = _contract_dependencies(graph, card_metric_ids, selected, selected_metrics) + + source_card_hash = _card_hash(card_id, config, metrics) + selection_hash = _hash({ + "resolver_version": RESOLVER_VERSION, "source": source, "mode": mode, + "metric_ids": selected, "query_ids": query_ids, + "required_entry_fields": [str(f.get("name")) for f in required_entry_fields], + }) + closure_hash = _hash({ + "resolver_version": RESOLVER_VERSION, "source": source, "mode": mode, + "card_metric_ids": card_metric_ids, "metric_ids": selected, "query_ids": query_ids, + "excluded_query_ids": excluded_query_ids, + "queries": [q.as_dict() for q in queries], + "required_entry_fields": [str(f.get("name")) for f in required_entry_fields], + "entry_fields": [dict(f) for f in entry_fields], + "binding_fingerprints": binding_fingerprints, + "contract_dependencies": contract_dependencies, + "unresolved": unresolved, + "on_missing": config.get("on_missing"), "defaults": dict(graph.get("defaults") or {}), + "source_card_hash": source_card_hash, + }) + return Closure( + source=source, mode=mode, whole_card=mode == WHOLE_CARD, + card_metric_ids=tuple(card_metric_ids), metric_ids=tuple(selected), query_ids=tuple(query_ids), + excluded_query_ids=tuple(excluded_query_ids), queries=tuple(queries), + required_entry_fields=required_entry_fields, entry_fields=entry_fields, + binding_fingerprints=binding_fingerprints, contract_dependencies=tuple(contract_dependencies), + unresolved=tuple(unresolved), resolver_version=RESOLVER_VERSION, source_card_hash=source_card_hash, + selection_hash=selection_hash, closure_hash=closure_hash, + on_missing=config.get("on_missing"), defaults=dict(graph.get("defaults") or {})) + + +def _card_hash(card_id: str, config: Mapping[str, Any], metrics: Sequence[Mapping[str, Any]]) -> str: + """整卡内容指纹:复用 caliber_identity.card_hash_of(只按指标语义字段 + 口径名/版本算,顺序不影响)。""" + from app.data.caliber_identity import card_hash_of + + return card_hash_of({"node_id": card_id, "metrics": list(metrics), + "caliber": config.get("caliber"), "caliber_version": config.get("caliber_version")}) + + +__all__ = ["BINDING_UNRESOLVED", "CARD_CHAINED", "CARD_EMPTY", "CODES", "CONFLICTING_SELECTION", "Closure", + "ClosureRefused", "DUPLICATE_METRIC_ID", "DUPLICATE_QUERY_ID", "EMPTY_SELECTION", "EXPLICIT", + "EXPRESSION_UNREADABLE", "METRIC_UNKNOWN", "NO_QUERY", "QUERY_NO_SQL", "Query", "RESOLVER_VERSION", + "SelectionIndex", "UNDECLARED_PARAMETER", "UNKNOWN_NODE", "UNSUPPORTED_PARAMETER", "UnresolvedClosure", + "WHOLE_CARD", "build", "duplicate_metric_ids", "effective_metrics", "query_id_of", "selection_index"] diff --git a/backend/app/ledger/compose.py b/backend/app/ledger/compose.py index 50374dd8..2b0bb1a4 100644 --- a/backend/app/ledger/compose.py +++ b/backend/app/ledger/compose.py @@ -14,14 +14,36 @@ 内联实例化只用到 tool 和 metrics 两种已放行的节点,证据照常封存,比对也照常复证(ledger/match 认出这些查询是助手 选用的,标 composed「助手选用」,不标「等价已证明」:选哪份口径是助手凭问法判断的)。 -**参数校验**(不合规拒收,原因交回模型改,GraphApplier.refusals): -- 只能选这一轮 look 能看到的那一版(每个工作流最新的已发布、未退役版本),而且那张卡能组合(derive.load_pinned:卡是 - 源头、每个输入都是取数节点第一行的格、取数模板只引用入口字段); +**只算选中的指标(K08 S2/S4)。** 模型写的 metrics 不只是「报告里引用哪几个数」:它决定这次真正要执行哪些取数——服务端按它 +算一份依赖闭包(ledger/closure),只拷选中的指标要用的取数节点、入口字段收窄到这次会用到的,并把选中的指标记在口径卡的 +caliber_from.metrics 上(运行时按 closure.effective_metrics 只算这几个)。一次选用里的指标一律按**源卡顺序**归一: +Composed.metrics、口径卡上记的 metrics、selection_hash 与执行数组都按这一份,调用方传的顺序与重复项都不影响结果。只选 A 时 +不再要求 B 的参数;A 和 B 共用一条 SQL 时那条 SQL 保留、并在结果里声明它还在算未选中的 B(不做投影)。点名的指标解析不出 +依赖(不在这张卡上、式子读不出来、绑定对不上)一律拒收,不静默退回整卡。 + +**选项是预筛,不是放行**(K08 S4)。look 读好的每一张卡带 ``Option``:``selectable_metrics``(能一个一个点名的指标,各自 +要哪些入口字段)与 ``unavailable_metrics``(用不了的与原因)按每个指标判(B 独有那条查询坏了、绑定对不上,只让 B 不可选); +至少有一个可选才给组合写法,一个也没有才标不能组合。``default_closure`` 是不点名(整卡)那一份闭包的摘要。这些摘要只含 +query_id、字段、工具、指纹与共享声明,**不含 SQL 正文、不含参数值**。真正选用(``instantiate``)时仍按这次要算的指标逐项 +硬校验,不拿预筛的结论放宽。 + +**参数校验**(不合规拒收,原因交回模型改,GraphApplier.refusals;判断都在 ledger/params,一处规则各入口同一套): +- 只能选这一轮 look 能看到的那一版(每个工作流的**推荐发布版本**,K07:Workflow.published_version,默认调用读它),而且 + 那张卡能组合(derive.load_pinned:卡是 + 源头、每个输入都是取数节点第一行的格、取数模板只引用入口字段、模板里的参数都在入口字段里声明过); - inputs 只认口径入口声明的字段,没写的补缺省值,再过 apps/forms 同一套表单校验(类型、可选值、必填、格式); +- 取数模板里的每个参数这次都要有值:没给、也没声明缺省值的(含声明成可选的)报 missing_parameter,不按空串发 SQL; - 参数要渲染进 SQL:写在引号里的不能带引号、反斜杠、换行;裸写的只能是数;写在注释里的不能带换行和注释结束符—— - 否则渲染出来的就不是那一版口径的 SQL 了; + 否则渲染出来的就不是那一版口径的 SQL 了(旧适配器承载不了的值明确拒绝,见 ledger/params); - metrics 只能是这张卡上的指标 id;id 不能和图里已有的节点撞。 +**值只渲染一次。** 拷出来的取数节点里,`{{ input.字段 }}` 在这一步渲染成字面值(值只被模板替换这一次),同时把参数 +契约写在节点的 `data.config["parameters"]` 里(ledger/params 的 marker):args 里已经是字面语句,运行时的模板渲染一概 +不碰它——不然值里带 `{{ vars.question }}` 这种文本会被运行时替换成那个变量的值,SQL 被数据改掉(K01 的二次渲染反例)。 +契约按**这次渲染出来的 args** 的哈希与节点绑定:复制走、改过 SQL 之后契约作废,那个节点回退成普通模板(正常渲染、 +正常判参数、画布照常扫变量)。契约里另记源模板哈希、规范化输入哈希、参数类型与写在哪儿、那一版取数节点的固定引用 +(出处只是个地址:本切片没有实现按它自动还原模板并核对)。 + 实例化是确定的:同样的版本、同样的操作得到一模一样的节点(测试锁住)。这里只是纯计算:版本快照由 look/calibers 的 CaliberKind 在开流之前用会话读好(GraphApplier.apply 是同步的,流里不碰库)。 """ @@ -30,11 +52,12 @@ from __future__ import annotations import copy import json import re -from collections.abc import Mapping +from collections.abc import Mapping, Sequence from dataclasses import dataclass, field from typing import Any -from app.ledger.derive import Pinned, caliber_block +from app.ledger import params +from app.ledger.derive import Pinned, caliber_block, declared_entry_fields #: 操作名 OP = "use_caliber" @@ -42,11 +65,10 @@ OP = "use_caliber" REFUSED = "ledger.use_caliber_refused" #: 操作 id:口径卡的节点 id,取数节点加它做前缀。简短英文小写下划线(同节点 id 的约定) _OP_ID = re.compile(r"^[a-z][a-z0-9_]{0,23}$") -_NUMBER = re.compile(r"^\s*-?\d+(?:\.\d+)?\s*$") #: 写给模型的拒收说明(也上界面:过程里那一行) NOT_LISTED = "只能选用这一轮查看到的已发布口径:「{workflow}」v{version} 不在里面(口径要先 look,版本以查看结果为准)" -WRONG_VERSION = "「{workflow}」这一轮能选用的是 v{latest}(最新的已发布版本),不是 v{version}" +WRONG_VERSION = "「{workflow}」这一轮能选用的是 v{latest}(这一轮的推荐发布版本),不是 v{version}" #: card 写错时交回的原因要能一次改对:说清 card 填什么、可填哪几个(节点 id);写成了自己起的 id 的另说一句 CARD_UNKNOWN = ("「{workflow}」v{version} 里没有口径卡「{card}」:card 要填那一版工作流图里口径卡的节点 id,可填的有 {cards}" "(照抄查看结果里 use_caliber 写法中的 card)") @@ -58,11 +80,11 @@ ID_TAKEN = "use_caliber 的 id「{id}」和图里已有的节点「{node}」撞 NO_METRICS = "use_caliber 的 metrics 要写这张口径卡上要用的指标 id(有:{metrics})" METRIC_UNKNOWN = "口径卡「{card}」上没有指标「{metric}」(有:{metrics})" FIELD_UNKNOWN = "口径「{workflow}」的入口没有字段「{name}」(有:{fields})" +#: 这个字段这一版入口声明过,只是不在这次选中的指标的范围里(K08 复核):说清是范围问题,不是口径没这个字段 +FIELD_OUT_OF_SELECTION = ("「{name}」这一版入口声明过,但不在这次选用的范围里:这次算 {metrics},只要 {fields};" + "口径「{workflow}」的入口还有 {others},那是别的指标要的——要用它就把那些指标一起选上") INPUTS_NOT_OBJECT = "use_caliber 的 inputs 要写成字段和值的对照(JSON 对象)" -QUOTED_VALUE = "参数「{name}」写在 SQL 的引号里,值里不能有引号、反斜杠或换行" -BARE_VALUE = "参数「{name}」直接写在 SQL 里(没有引号),只能是数,当前为「{value}」" -COMMENT_VALUE = "参数「{name}」写在 SQL 的注释里,值里不能有换行或注释结束符" -TEMPLATE_UNREADABLE = "取数节点的 SQL 模板认不出参数写在哪:{reason}" +TEMPLATE_UNREADABLE = params.UNREADABLE_TEXT class ComposeRefused(Exception): @@ -75,7 +97,17 @@ class ComposeRefused(Exception): @dataclass(frozen=True) class Option: - """这一轮能选用的一张口径卡:读好的那一版(pinned),或者不能组合的原因(reason)。""" + """这一轮能选用的一张口径卡:读好的那一版(pinned),以及**按指标**的可组合性(K08 S4)。 + + - ``selectable_metrics``:能一个一个点名的指标(按源卡顺序)。每项是这一份依赖的摘要(``closure.summary()`` 加 + ``metric_id`` / ``name``):这次要用的入口字段、要执行的查询(query_id、节点、工具、各自算谁、共享声明)、绑定指纹 + 与两份身份哈希——**没有 SQL 正文、没有参数值**。 + - ``unavailable_metrics``:用不了的指标与原因(按源卡顺序)。 + - ``default_closure``:不点名(整卡)那一份闭包的摘要;整卡算不出来时是 None,原因在 ``reason``。 + + ``composable`` 只看「至少有一个指标可选」:B 独有那条查询坏了、绑定对不上,A 照旧能选。这一层只是预筛,不改任何 + 判断——真正选用时 ledger/compose.instantiate 按这次要算的指标逐项硬校验(未知指标、参数、绑定),不靠预筛放宽。 + """ workflow_id: str workflow_name: str @@ -85,10 +117,16 @@ class Option: card: str pinned: Pinned | None = None reason: str | None = None + selectable_metrics: tuple[dict[str, Any], ...] = () + unavailable_metrics: tuple[dict[str, Any], ...] = () + default_closure: dict[str, Any] | None = None @property def composable(self) -> bool: - return self.pinned is not None and self.reason is None + """这一轮能不能选用:至少有一个指标可选。没做过分指标分析的老调用方(直接给了 pinned)按能不能读出这一版算。""" + if self.pinned is None: + return False + return bool(self.selectable_metrics) or self.reason is None @dataclass @@ -101,6 +139,8 @@ class Composed: edges: list[dict[str, Any]] metrics: list[dict[str, Any]] inputs: dict[str, Any] = field(default_factory=dict) + #: 这次选择的依赖闭包(K08 S2):身份、这次要执行的查询、共享查询还在算谁(结果里照实带出去) + closure: Any = None @property def fetch_ids(self) -> list[str]: @@ -110,11 +150,26 @@ class Composed: """交给界面(过程里那一行)、记进这一轮的操作流的结果。不放 SQL、不放参数值(参数值助手自己写的,界面不必再给)。""" from app.ledger.labels import LEVEL_TEXT - return {"status": "ok", "workflow_id": self.option.workflow_id, "workflow_name": self.option.workflow_name, - "version": self.option.version, "level": self.option.level, - "level_text": LEVEL_TEXT.get(self.option.level, ""), "card": self.option.card, "card_id": self.op_id, - "fetches": self.fetch_ids, "metrics": [{"id": m["id"], "name": m["name"]} for m in self.metrics], - "nodes": len(self.nodes)} + out = {"status": "ok", "workflow_id": self.option.workflow_id, "workflow_name": self.option.workflow_name, + "version": self.option.version, "level": self.option.level, + "level_text": LEVEL_TEXT.get(self.option.level, ""), "card": self.option.card, "card_id": self.op_id, + "fetches": self.fetch_ids, "metrics": [{"id": m["id"], "name": m["name"]} for m in self.metrics], + "nodes": len(self.nodes)} + if self.closure is not None: + # 这次选择的身份(selection_hash:同一批指标同一批查询)与整份闭包的身份(closure_hash:绑定变了它就变) + out["selection"] = {"mode": self.closure.mode, "metric_ids": list(self.closure.metric_ids), + "query_ids": list(self.closure.query_ids), + "excluded_query_ids": list(self.closure.excluded_query_ids), + "selection_hash": self.closure.selection_hash, + "closure_hash": self.closure.closure_hash, + "resolver_version": self.closure.resolver_version, + "source_card_hash": self.closure.source_card_hash} + # 共享查询照实声明:这条 SQL 这次也还在算这些没选中的指标(不做投影) + shared = [{"query_id": q.query_id, "node_id": q.node_id, "computes_unselected": list(q.computes_unselected)} + for q in self.closure.queries if q.computes_unselected] + if shared: + out["shared_queries"] = shared + return out def signature(op: Mapping[str, Any]) -> str: @@ -126,16 +181,20 @@ def _names(items: list[str]) -> str: return "、".join(items[:12]) or "无" -def _slot_contexts(pinned: Pinned) -> dict[str, set[str]]: - """取数 SQL 模板里每个入口字段写在哪:{字段: {quoted / bare / comment}}。认不出的抛 ComposeRefused。""" - return slot_contexts(pinned.fetches) +def _selected_ids(pinned: Pinned) -> list[str]: + """这一份(可能裁过的)口径这次算哪些指标:裁过就是选择里的那几个(按源卡顺序),没裁就是卡上的全部。""" + closure = pinned.closure + if closure is not None and not closure.whole_card: + return [str(m) for m in closure.metric_ids] + return [str(m["id"]) for m in pinned.metrics] def slot_contexts(nodes: Any, *, strict: bool = True) -> dict[str, set[str]]: - """几个调用工具节点的 args.sql 里每个入口字段写在哪(见 _slot_contexts)。按口径正式出具(ledger/issue)也按它查参数: - strict=False 时认不出写法的那条(引用了运行时的变量)跳过,不抛——那张图里别的节点怎么写不归出具管。""" - from app.data.sql_semantics import _NotComparable, _template_slots + """几个调用工具节点的 args.sql 里每个入口字段写在哪:{字段: {quoted / bare / comment}}。 + 判断在 ledger/params(各入口同一套参数语义):这里只把 ``params.slots_of`` 的结果收成 {字段: {写在哪儿}},给要看 + 承载方式的地方(``params.literal_problem`` 的那一套)读;按指标的可组合性(look/calibers.metric_options)走闭包, + 不从这里拿。strict=False 时认不出写法的那条跳过、不抛。""" out: dict[str, set[str]] = {} for node in nodes: if not isinstance(node, dict): @@ -145,31 +204,52 @@ def slot_contexts(nodes: Any, *, strict: bool = True) -> dict[str, set[str]]: if not isinstance(sql, str): continue try: - spans, _ = _template_slots(sql) - except _NotComparable as e: + slots = params.slots_of(sql) + except params.ParameterRefused as e: if not strict: continue - raise ComposeRefused(TEMPLATE_UNREADABLE.format(reason=str(e))) from None - for _, _, slot in spans: + raise ComposeRefused(TEMPLATE_UNREADABLE.format(reason=e.problems[0].message)) from None + for slot in slots: out.setdefault(slot.field, set()).add(slot.context) return out def _value_problem(name: str, value: Any, contexts: set[str]) -> str | None: - text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False) \ - if isinstance(value, (dict, list)) else str(value) - if "quoted" in contexts and any(ch in text for ch in ("'", "\\", "\n", "\r")): - return QUOTED_VALUE.format(name=name) - if "bare" in contexts and not (isinstance(value, (int, float)) and not isinstance(value, bool)) \ - and not (isinstance(value, str) and _NUMBER.match(value)): - return BARE_VALUE.format(name=name, value=text[:40]) - if "comment" in contexts and ("\n" in text or "\r" in text or "*/" in text): - return COMMENT_VALUE.format(name=name) - return None + """值写在 SQL 的哪个位置、旧适配器(内联文本替换)承载得了吗(ledger/params.literal_problem)。""" + return params.literal_problem(name, value, contexts) -def check_inputs(pinned: Pinned, inputs: Any) -> dict[str, Any]: - """按口径入口的字段校验助手给的参数,补缺省值,交回要渲染进模板的那一份。不合规抛 ComposeRefused(一句一处)。""" +#: 点名要算的指标解析不出依赖(derive.select_pinned 的未决项):照实交回,拒收这次选用 +SELECTION_REFUSED = "口径卡「{card}」这次点名的指标算不出依赖:{reason}" + + +def _selected(pinned: Pinned, metric_ids: "Sequence[str] | None" = None, whole_card: bool = False) -> Pinned: + """按这次要算的指标裁一份口径(derive.select_pinned:只留这次要执行的取数、入口字段收窄、带上选择的闭包)。 + + 算不出依赖(点名的指标不在这张卡上、式子读不出来、绑定对不上、点名的取数没有可读 SQL)抛 ComposeRefused 交回模型改 + ——**不静默退回整卡**。""" + from app.ledger import derive + + try: + return derive.select_pinned(pinned, metric_ids=metric_ids, whole_card=whole_card) + except derive.NotDerivable as e: + raise ComposeRefused(SELECTION_REFUSED.format(card=pinned.card_title, reason=e.message)) from None + + +def check_inputs(pinned: Pinned, inputs: Any, *, metric_ids: "Sequence[str] | None" = None, + whole_card: bool = False) -> dict[str, Any]: + """按口径入口的字段校验助手给的参数,补缺省值,交回这次要渲染进取数节点的值(拷节点时用它渲染一次)。 + + metric_ids / whole_card 给了就先按这次要算的指标裁一份(_selected):只按**这次真正要执行的取数**判参数与入口字段—— + 只选 A 时不再要求 B 那条 SQL 的参数,B 独有的入口字段也不在这次范围里(照实拒)。不给就是整张卡的入口(和以前一样)。 + + 字段这一栏分两种说法(K08 复核):这一版入口**声明过**、只是不在这次选中的指标的范围里 → FIELD_OUT_OF_SELECTION + (说清这次算哪些指标、只要哪些字段、剩下的字段是谁要的);入口**根本没声明** → FIELD_UNKNOWN。两种都拒,不改行为。 + + 不合规抛 ComposeRefused(一句一处):字段不认识、必填没给、类型/可选值不对、模板里的参数这次没有值(missing)、 + 模板引用了没声明的字段(undeclared)、值承载不了(literal)。""" + if metric_ids is not None or whole_card: + pinned = _selected(pinned, metric_ids=metric_ids, whole_card=whole_card) from app.apps.forms import input_schema, validate_form if inputs is None: @@ -178,24 +258,42 @@ def check_inputs(pinned: Pinned, inputs: Any) -> dict[str, Any]: raise ComposeRefused(INPUTS_NOT_OBJECT) fields = {str(f.get("name")).strip(): f for f in pinned.entry_fields if isinstance(f.get("name"), str)} if unknown := [k for k in inputs if k not in fields]: + # 字段「不在本次选择范围」与「口径没有这个字段」是两回事(K08 复核):前者说清这次算哪些指标、只要哪些字段 + declared = declared_entry_fields(pinned) + names = {str(f.get("name") or "").strip() for f in declared} + if later := [k for k in unknown if k in names]: + raise ComposeRefused(FIELD_OUT_OF_SELECTION.format( + name=later[0], workflow=pinned.workflow_name, metrics=_names(_selected_ids(pinned)), + fields=_names(list(fields)), + others=_names([str(f.get("name")) for f in declared + if str(f.get("name") or "").strip() not in fields]))) raise ComposeRefused(FIELD_UNKNOWN.format(workflow=pinned.workflow_name, name=unknown[0], fields=_names(list(fields)))) values = {name: copy.deepcopy(f.get("default")) for name, f in fields.items() if f.get("default") not in (None, "")} - values.update({k: v for k, v in inputs.items() if v is not None and v != ""}) + # 收值和试跑同一份(params.provided):显式传的空串算没给——字段没声明缺省值时就是缺参数(上面判), + # 声明了 default="" 的照缺省值走(作者写的就是「空值不过滤」) + values.update(params.provided(inputs)) if errors := validate_form(input_schema(list(pinned.entry_fields)), values): raise ComposeRefused(";".join(e["message"] for e in errors)) - contexts = _slot_contexts(pinned) - for name, value in values.items(): - if problem := _value_problem(name, value, contexts.get(name, set())): - raise ComposeRefused(problem) + problems = params.check_nodes(pinned.fetches, fields=pinned.entry_fields, values=values, + where=f"口径「{pinned.workflow_name}」的入口") + if problems: + raise ComposeRefused(params.describe(problems)) return values def instantiate(option: Option, op: Mapping[str, Any], *, taken: set[str]) -> Composed: - """按选用的那一版确定性地实例化(见模块说明)。taken 是图里已有的节点 id。不合规抛 ComposeRefused。""" + """按选用的那一版确定性地实例化(见模块说明)。taken 是图里已有的节点 id。不合规抛 ComposeRefused。 + + op.metrics 贯穿参数校验与拷贝:先按它裁一份(_selected 的依赖闭包),check_inputs 按**这次真正要执行的取数**判参数 + (只选 A 时不再要求 B 的参数),caliber_block 也只拷 A 那条查询、把这次的选择记在口径卡上。选中的指标解析不出依赖 + ——拒收,不静默退回整卡。 + + 一次选用里的指标按**源卡顺序**归一(同一批指标换个写法——调用方传的顺序、重复项——得到同一份结果:Composed.metrics、 + 口径卡上记的 metrics、selection_hash 与执行数组都按这一份,见 K08 S4)。""" pinned = option.pinned - if pinned is None or option.reason is not None: + if pinned is None or not option.composable: raise ComposeRefused(NOT_COMPOSABLE.format(workflow=option.workflow_name, version=option.version, card=option.card, reason=option.reason or "读不到这一版")) op_id = str(op.get("id") or "").strip() @@ -208,14 +306,26 @@ def instantiate(option: Option, op: Mapping[str, Any], *, taken: set[str]) -> Co raise ComposeRefused(NO_METRICS.format(metrics=_names(list(on_card)))) if missing := [m for m in wanted if m not in on_card]: raise ComposeRefused(METRIC_UNKNOWN.format(card=option.card, metric=missing[0], metrics=_names(list(on_card)))) - values = check_inputs(pinned, op.get("inputs")) - block = caliber_block(pinned, prefix=f"{op_id}_", card_id=op_id, inputs=values) + selected = _selected(pinned, wanted) + values = check_inputs(selected, op.get("inputs")) + block = caliber_block(selected, prefix=f"{op_id}_", card_id=op_id, inputs=values) if clash := next((str(n["id"]) for n in block.nodes if str(n["id"]) in taken), None): raise ComposeRefused(ID_TAKEN.format(id=op_id, node=clash)) nodes = block.nodes edges = [{"source": a["id"], "target": b["id"]} for a, b in zip(nodes, nodes[1:])] - metrics = [{"id": m, "name": str(on_card[m].get("name") or m)} for m in wanted] - return Composed(op_id=op_id, option=option, nodes=nodes, edges=edges, metrics=metrics, inputs=values) + metrics = [{"id": m, "name": str(on_card[m].get("name") or m)} for m in _ordered(pinned, selected, wanted)] + return Composed(op_id=op_id, option=option, nodes=nodes, edges=edges, metrics=metrics, inputs=values, + closure=selected.closure) + + +def _ordered(pinned: Pinned, selected: Pinned, wanted: list[str]) -> list[str]: + """这次算的指标 id,按**源卡顺序**归一(和 caliber_from.metrics、运行时、selection_hash 同一份)。 + + 裁剪过的那一份带着闭包,直接读它;没有闭包(理论上到不了)就按卡上指标的顺序取。""" + closure = selected.closure + if closure is not None: + return [str(m) for m in closure.metric_ids] + return [str(m["id"]) for m in pinned.metrics if str(m["id"]) in set(wanted)] class Composer: diff --git a/backend/app/ledger/derive.py b/backend/app/ledger/derive.py index 8d37d063..b45e3164 100644 --- a/backend/app/ledger/derive.py +++ b/backend/app/ledger/derive.py @@ -16,6 +16,13 @@ cell(nodes.X, 0, '列')、X 是查库的调用工具节点(look/calibers.card_ 模板只引用入口字段({{ input.字段 }})——引用 vars.、nodes.、模板函数(file_text……)的,拷出来就拿不到同样的值,照实 拒收、给原因(NotDerivable)。工作流、版本、节点不在了也照实说。 +**只算一部分指标(K08 S2)**:load_pinned / select_pinned 收可选的 metric_ids(或显式 whole_card=True)。给了选择就先算一份 +依赖闭包(ledger/closure),只拷这次真正要执行的取数节点、入口字段收窄到这次要用的,并把选中的指标记进口径卡的 +caliber_from.metrics(运行时按 closure.effective_metrics 只算这几个)。没给选择就照旧整卡——图、参数、身份一个字不变。 +未决依赖(点名的指标不在这张卡上、式子读不出来、绑定对不上、点名的取数没有可读 SQL)一律照实拒 +(NotDerivable,code=derive.selection_unresolved),**不静默退回整卡**;共享给未选中指标的那条 SQL 照样保留(它还在算谁 +记在闭包的 computes_unselected 上,不做投影)。 + **已实现的**:caliber_probe —— 一份口径的取数 + 口径卡(评测口径题的期望);reconcile —— 口径对账(第 3 波, reconcile_graph);组合式问数用的 caliber_block(card_id, inputs)(第 3 波);recall —— 口径召回(第 4 波,recall_graph)。 @@ -39,11 +46,16 @@ from __future__ import annotations import copy import re from collections.abc import Iterable, Mapping, Sequence -from dataclasses import dataclass, field -from typing import Any +from dataclasses import dataclass, field, replace +from typing import TYPE_CHECKING, Any from sqlalchemy.ext.asyncio import AsyncSession +from app.ledger import params + +if TYPE_CHECKING: # 运行时按需 import:closure 反过来要用这一层(entry_fields) + from app.ledger.closure import Closure + #: 派生图的种类(见模块说明) KINDS = ("caliber_probe", "reconcile", "recall") @@ -52,6 +64,13 @@ GONE = "derive.version_gone" NOT_CARD = "derive.not_caliber_card" NOT_REUSABLE = "derive.not_reusable" TEMPLATE = "derive.fetch_template" +#: 取数模板引用了入口没声明的参数(ledger/params.UNDECLARED):拷出来渲染不出那一版口径的 SQL +UNDECLARED_PARAMETER = "derive.undeclared_parameter" +#: 业务定义(统计时间口径、退款规则)和取数节点上的受控绑定对不上(K04):派生出来跑的还是旧 SQL, +#: 这一版的数不能冒充新定义(见 ledger/bindings) +BINDING_UNALIGNED = "derive.binding_unaligned" +#: 点名要算的指标解析不出依赖闭包(K08 S2):闭包的每一条未决原样写进 message,照实拒绝、不静默退回整卡 +SELECTION = "derive.selection_unresolved" #: 派生图自己的入口、出口节点 id(和拷出来的节点撞了就加后缀) ENTRY_ID = "derived_in" @@ -68,17 +87,24 @@ TEMPLATE_REASON = ("取数节点「{node}」的模板引用了「{ref}」:只 class NotDerivable(Exception): - """不能从这一版派生只读图。message 给人看(照实说哪一环不行),code 给程序认。""" + """不能从这一版派生只读图。message 给人看(照实说哪一环不行),code 给程序认。 - def __init__(self, message: str, code: str) -> None: + problems:参数完整性问题(ledger/params.Problem)的原样一份,入口据此回结构化错误(problems 数组);不是参数问题为空。""" + + def __init__(self, message: str, code: str, *, problems: Sequence[Any] = ()) -> None: super().__init__(message) self.message = message self.code = code + self.problems = tuple(problems) @dataclass(frozen=True) class Pinned: - """读好的一版口径:那一版的图、口径卡、它读的取数节点、入口字段。只从不可变的版本快照读。""" + """读好的一版口径:那一版的图、口径卡、它读的取数节点、入口字段。只从不可变的版本快照读。 + + 给了选择(select_pinned / load_pinned(metric_ids=…))的这份只带**这次要执行**的那几个取数节点与前缀入口字段,另带 + 这份选择的依赖闭包(``closure``);没给选择就是整卡,闭包是整卡的(附上供调用方读身份,不在这里判未决)。 + """ workflow_id: str workflow_name: str @@ -91,14 +117,21 @@ class Pinned: published: bool retired: bool card: dict[str, Any] - #: 口径卡读的取数节点(图里的原始 JSON),按图里的先后 + #: 口径卡读的取数节点(图里的原始 JSON),按图里的先后;给了选择时只有这次要执行的那几个 fetches: tuple[dict[str, Any], ...] - #: card_inputs 认出的 [(取数节点, 工具, 列)] + #: card_inputs 认出的 [(取数节点, 工具, 列)];给了选择时只有留下的那几个节点 reads: tuple[tuple[str, str, tuple[str, ...]], ...] - #: 入口节点声明的字段(原始 JSON:name、type、required、default……) + #: 入口节点声明的字段(原始 JSON:name、type、required、default……);给了选择时收窄到这次真正会用到的 entry_fields: tuple[dict[str, Any], ...] #: 图级 defaults(节点上没写的配置按它取,照抄才和原图取值一致) defaults: dict[str, Any] + #: 业务绑定(K04)的判定:这一版的业务定义(时间口径、退款规则)和取数节点上的受控绑定是不是同步 + #: (ledger/bindings 的 Report.as_dict())。load_pinned 已经保证只有 aligned / unbound 的卡才派得出来。 + binding: dict[str, Any] = field(default_factory=dict) + #: 读这一版时留下的那张图(只读):按选择再算一次依赖闭包时用它,不重读库、也不再回内存里那份快照 + graph: dict[str, Any] = field(default_factory=dict) + #: 这一版的依赖闭包(K08):没给选择时是整卡闭包;给了选择时就是这次选择的那一份,也是这次裁剪的依据 + closure: "Closure | None" = None @property def card_title(self) -> str: @@ -200,8 +233,13 @@ def entry_fields(graph: Mapping[str, Any]) -> tuple[dict[str, Any], ...]: return tuple(out.values()) -async def load_pinned(session: AsyncSession, workflow_id: str, version: int, node_id: str) -> Pinned: - """读 workflow_id@version 里的口径卡 node_id。不能派生的抛 NotDerivable(照实说哪一环不行)。""" +async def read_pinned(session: AsyncSession, workflow_id: str, version: int, node_id: str) -> Pinned: + """读 workflow_id@version 里的口径卡 node_id,**不判依赖**:工作流、版本、节点在不在、是不是口径卡(不在就抛 + NotDerivable);读一版图只有这一处。交回的 Pinned 有那一版的图、卡、入口字段与图级缺省值;取数节点空着,reads 是 + 「整卡认得出的那一份」(card_inputs 读不出来就是空,不在这里判能不能用)。 + + 调用方按选择裁(select_pinned)或按整卡门禁判(load_pinned)。look 的按指标可组合性(calibers.metric_options)也从 + 这一份出发:B 独有那条查询坏了不该牵连 A,所以它不能走整卡门禁那一条路。""" from app.apps import versions as app_versions from app.db.models import Workflow from app.look.calibers import card_inputs @@ -218,22 +256,147 @@ async def load_pinned(session: AsyncSession, workflow_id: str, version: int, nod raise NotDerivable(f"「{workflow.name}」v{version} 里没有节点 {node_id}", GONE) if card.get("type") != "metrics": raise NotDerivable(f"「{workflow.name}」v{version} 里的 {node_id} 不是口径卡", NOT_CARD) - inputs, reason = card_inputs(graph, node_id) + readable, _ = card_inputs(graph, node_id) + return Pinned(workflow_id=workflow.id, workflow_name=workflow.name, version=int(version), node_id=node_id, + level=row.level, published=app_versions.is_published(row, current=workflow.published_version), + retired=row.retired_at is not None, card=copy.deepcopy(card), fetches=(), + reads=tuple((i["node"], i["tool"], tuple(i["columns"])) for i in readable), + entry_fields=entry_fields(graph), defaults=copy.deepcopy(graph.get("defaults") or {}), graph=graph) + + +async def load_pinned(session: AsyncSession, workflow_id: str, version: int, node_id: str, *, + metric_ids: Sequence[str] | None = None, whole_card: bool = False) -> Pinned: + """读 workflow_id@version 里的口径卡 node_id。不能派生的抛 NotDerivable(照实说哪一环不行)。 + + metric_ids / whole_card 给了就只按这次要算的指标读(K08 S2):取数节点、入口字段、参数与绑定判定都收窄到这次的范围 + (未选中指标独有那条查询的坏 SQL、坏绑定不牵连选中的),未决依赖照实拒(code=SELECTION)——**不静默退回整卡**。 + 不给就是整张卡:门禁、图、身份和以前一字不差(整卡闭包照样算一份附在 Pinned 上,只是不在这里判它有没有未决)。 + + 唯一两条路径都不放行的是**指标 id 重复**(同一张卡上两个指标用同一个 id,code=duplicate_metric_id):那是卡的指标 + 身份本身坏了——闭包按定义解析、运行时按指标集筛、下游按位置取 nodes.<卡>.metrics[i] 会各算一份,谁是谁说不清。 + """ + from app.look.calibers import card_inputs + + pinned = await read_pinned(session, workflow_id, version, node_id) + title = pinned.card_title + # 指标 id 重复(同一张卡上两个指标用了同一个 id):卡的指标身份本身坏了——闭包按定义解析、运行时按指标集筛、下游按 + # 位置取 nodes.<卡>.metrics[i] 会各算一份,谁是谁说不清。这不是「某个指标的问题」,哪条路径都不放行、也不静默取一份 + from app.ledger.closure import DUPLICATE_METRIC_ID, duplicate_metric_ids + + if duplicates := duplicate_metric_ids(pinned.metrics): + raise NotDerivable(f"「{pinned.workflow_name}」v{pinned.version} 的口径卡「{title}」上有指标 id 重复:" + f"{'、'.join(duplicates)}——同一张卡上每个指标 id 只能有一个,先改成不重的 id", + DUPLICATE_METRIC_ID) + if metric_ids is not None: + # 点名要算哪几个:整卡的「每个输入都要是查库结果里的格」那道门禁不在这里判——B 独有那条查询再糟也不该牵连 A; + # 收窄到这次的范围、逐条判依赖,判不出来照实拒(收窄与判定都在 select_pinned 的闭包里) + return select_pinned(pinned, metric_ids=metric_ids, whole_card=whole_card) + graph, node = pinned.graph, pinned.node_id + inputs, reason = card_inputs(graph, node) if reason is not None: - title = (card.get("data") or {}).get("label") or node_id - raise NotDerivable(f"「{workflow.name}」v{version} 的口径卡「{title}」不能复用:{reason}", NOT_REUSABLE) + raise NotDerivable(f"「{pinned.workflow_name}」v{pinned.version} 的口径卡「{title}」不能复用:{reason}", NOT_REUSABLE) wanted = {i["node"] for i in inputs} fetches = tuple(copy.deepcopy(n) for n in graph.get("nodes") or [] if isinstance(n, dict) and n.get("id") in wanted) - for node in fetches: - if problem := template_problem(str(node["id"]), _config(node)): - raise NotDerivable(f"「{workflow.name}」v{version} 的{problem}", TEMPLATE) - return Pinned( - workflow_id=workflow.id, workflow_name=workflow.name, version=int(version), node_id=node_id, - level=row.level, published=app_versions.is_published(row, current=workflow.published_version), - retired=row.retired_at is not None, card=copy.deepcopy(card), fetches=fetches, - reads=tuple((i["node"], i["tool"], tuple(i["columns"])) for i in inputs), - entry_fields=entry_fields(graph), defaults=copy.deepcopy(graph.get("defaults") or {})) + for node_ in fetches: + if problem := template_problem(str(node_["id"]), _config(node_)): + raise NotDerivable(f"「{pinned.workflow_name}」v{pinned.version} 的{problem}", TEMPLATE) + # 模板里的参数要和入口字段对得上(ledger/params,各入口同一套判断):引用入口没声明的字段,派生出来渲染的就是空串 + # ——在派生这一步就说清楚,别等发出的 SQL 少了个值 + if problems := params.check_nodes(fetches, fields=pinned.entry_fields, + where=f"「{pinned.workflow_name}」v{pinned.version} 的入口声明的字段"): + first = problems[0] + raise NotDerivable(f"「{pinned.workflow_name}」v{pinned.version} 的取数节点「{first.node_id or node}」:" + f"{first.message}", UNDECLARED_PARAMETER if first.code == params.UNDECLARED else TEMPLATE, + problems=problems) + # K04:指标里的业务定义(统计时间口径、退款规则)和取数节点上的受控绑定对不上的,不许派生——派生出来跑的还是 + # 那张旧 SQL,这一版的数不能冒充新定义。旧资产(没声明这两个字段)是 unbound,照旧放行 + from app.ledger import bindings as caliber_bindings + + alignment = caliber_bindings.analyze(graph, node) + if alignment.blocked: + raise NotDerivable(f"「{pinned.workflow_name}」v{pinned.version} 的口径卡「{title}」:{alignment.reason}", + BINDING_UNALIGNED) + pinned = replace(pinned, fetches=fetches, + reads=tuple((i["node"], i["tool"], tuple(i["columns"])) for i in inputs), + binding=alignment.as_dict()) + # 显式整卡:和缺省那条路径同一道门禁,再要一份整卡闭包(闭包有未决就照实拒,不静默放宽) + return select_pinned(pinned, whole_card=True) if whole_card else select_pinned(pinned) + + +def select_pinned(pinned: Pinned, *, metric_ids: Sequence[str] | None = None, + whole_card: bool = False) -> Pinned: + """按选择从**读好的一版**里裁出一份 Pinned(纯函数、无 IO):只留这次要执行的取数节点、入口字段收窄到这次会用到的, + 并把这次选择的依赖闭包附在闭包字段上。别的(卡、口径名、版本、级别、图级缺省值)原样。 + + - 没给选择(metric_ids 是 None、whole_card 不是 True):原样交回,只把整卡闭包附上去(供调用方读身份与依赖), + 不在这里判有没有未决——那几道门禁在 load_pinned 里照旧; + - 给了选择:先看这份闭包能不能用,不能用一律 NotDerivable(code=SELECTION,每一条未决原样写进 message), + **绝不静默退回整卡**;能用就只留闭包里的那些查询(共享给未选中指标的那条 SQL 照样保留,它还在算谁记在 + Query.computes_unselected 上),入口字段收窄到这次真正引用的那些,绑定判定也只看这次要执行的那些节点。 + + pinned.graph 是读这一版时留下的那张图(只读)。同一版、同一份选择,每次得到同一份结果。 + """ + from app.ledger import closure as caliber_closure + + graph = pinned.graph if isinstance(pinned.graph, dict) else {} + explicit = metric_ids is not None or whole_card + try: + selection = caliber_closure.build(graph, pinned.workflow_id, pinned.version, pinned.node_id, + metric_ids=metric_ids, whole_card=whole_card) + except caliber_closure.ClosureRefused as e: + if not explicit: + return pinned # 手里没有这一版的图(手工拼的 Pinned):算不了闭包,旧路径照旧 + raise NotDerivable(f"口径卡「{pinned.card_title}」算不出依赖:{e}", SELECTION) from None + if not explicit: + return replace(pinned, closure=selection) + # 每个点名的指标读的输入都要能复用(cell(nodes.X, 0, '列')、X 是查库的调用工具节点):判定与整卡那道门禁、 + # look 的按指标可组合性(calibers.metric_options)同一份 metric_inputs。B 读的是别的节点,不牵连 A + from app.look.calibers import metric_inputs as caliber_metric_inputs + + named = [m for m in pinned.metrics if str(m.get("id")) in set(metric_ids or [])] + for metric in named: + _, reason = caliber_metric_inputs(graph, pinned.node_id, metric) + if reason is not None: + raise NotDerivable(f"「{pinned.workflow_name}」v{pinned.version} 的口径卡「{pinned.card_title}」" + f"不能复用:{reason}", NOT_REUSABLE) + try: + selection.require() + except caliber_closure.UnresolvedClosure as e: + raise NotDerivable( + f"「{pinned.workflow_name}」v{pinned.version} 的口径卡「{pinned.card_title}」这次点名的指标算不出来:" + f"{problems_text(e.problems)}。请把依赖补齐,或按整卡再来一次", SELECTION) from None + if selection.whole_card: + return replace(pinned, closure=selection) + kept = {q.node_id for q in selection.queries} + names = {str(f.get("name")) for f in selection.required_entry_fields} + from app.ledger import bindings as caliber_bindings + + selected = [m for m in pinned.metrics if str(m.get("id")) in set(selection.metric_ids)] + # 这次要执行的取数节点从**图**里取(不靠整卡那一步认出来的那份):B 独有那条查询再糟,也不影响 A 被认出来 + fetches = tuple(copy.deepcopy(n) for n in graph.get("nodes") or [] + if isinstance(n, Mapping) and str(n.get("id")) in kept) + return replace(pinned, fetches=fetches, + reads=tuple(r for r in pinned.reads if str(r[0]) in kept), + entry_fields=tuple(f for f in pinned.entry_fields if str(f.get("name") or "").strip() in names), + binding=caliber_bindings.analyze(graph, pinned.node_id, selected).as_dict(), + closure=selection) + + +def problems_text(problems: Sequence[Mapping[str, Any]]) -> str: + """闭包的每一条未决收成一句话:前四条原样带各自的机器码,多的只报个数(不逐条铺开)。 + + ``select_pinned`` 的拒收消息与 look 的按指标可组合性(calibers.metric_options)都读这一份,不各写一遍措辞。""" + said = ";".join(f"{p.get('message') or p.get('code')}({p.get('code')})" for p in problems[:4]) + more = f";另有 {len(problems) - 4} 项" if len(problems) > 4 else "" + return said + more + + +def _problems_text(problems: Sequence[Mapping[str, Any]]) -> str: + """闭包的每一条未决收成一句话:前四条原样带各自的机器码,多的只报个数(不逐条铺开)。""" + said = ";".join(f"{p.get('message') or p.get('code')}({p.get('code')})" for p in problems[:4]) + more = f";另有 {len(problems) - 4} 项" if len(problems) > 4 else "" + return said + more # ========================================================================== @@ -247,7 +410,10 @@ def _node(nid: str, ntype: str, label: str, **config: Any) -> dict[str, Any]: def render_inputs(value: Any, inputs: Mapping[str, Any]) -> Any: """配置里每一段字的 {{ input.字段 }} 按 inputs 渲染成字面值(和运行时同一个渲染器 engine/expressions.render_template)。 - load_pinned 已经保证取数节点的模板只引用入口字段。别的值原样。""" + load_pinned 已经保证取数节点的模板只引用入口字段。别的值原样。 + + 渲染只能发生一次:这里渲染出来的东西交给运行时之后,运行时的模板渲染不能再碰它(caliber_block 会在节点上写一份参数 + 契约,engine/nodes/tools.run_tool 按它跳过渲染)。渲染过的结果被再解释一遍,值里的 {{ }} 就不是数据了(K01)。""" from app.engine.expressions import render_template if isinstance(value, str): @@ -260,16 +426,27 @@ def render_inputs(value: Any, inputs: Mapping[str, Any]) -> Any: def caliber_block(pinned: Pinned, *, prefix: str = "", upgrade_policy: str | None = None, - card_id: str | None = None, inputs: Mapping[str, Any] | None = None) -> Block: + card_id: str | None = None, inputs: Mapping[str, Any] | None = None, + metrics: Sequence[str] | None = None, whole_card: bool = False) -> Block: """一份口径:拷出取数节点(id、配置原样;prefix 不为空时改名为 prefix + 原 id)+ 一张 caliber_from 固定到那一版的 口径卡(id 同原卡,带前缀时同样改名;「缺输入时」照抄原卡)。 + metrics / whole_card 给了就先按这次要算的指标裁一份(select_pinned 的闭包):只拷这次要执行的取数节点,改名映射 + (caliber_from.nodes)只列它们,拷出来的卡照旧固定到那一版。裁剪过的口径卡多一项 caliber_from.metrics(这次算哪几个 + 指标,按源卡顺序)——运行时按它只算这几个(closure.effective_metrics);整卡时不写这一项,行为和以前一样。 + upgrade_policy:钉住的版本有了新的已发布版本时这一段怎么处置(recompute / dual / incomparable,没有缺省)。写在 本地口径卡上,判断走和正式运行同一个 engine/governance.unresolved_caliber_upgrades;不给就不写(有新版本时那个 判断报「待处置」)。带前缀时口径卡的 caliber_from 带改名映射 nodes(metrics 运行时按它改写式子,见模块说明)。 组合式问数(ledger/compose.py)另给两项:card_id 是口径卡在新图里的 id(缺省 prefix + 原卡 id);inputs 给了的话, - 取数节点配置里的 {{ input.字段 }} 按它渲染成字面值——拷进问数据的图里,那张图的入口没有口径的入口字段。""" + 取数节点配置里的 {{ input.字段 }} **在这里渲染成字面值**(值只被模板替换这一次),并在节点上写一份按这份渲染结果的 + 哈希与节点绑定的参数契约(ledger/params 的 marker):args 里已经是字面语句,运行时的模板渲染一概不碰它;复制走、 + 改过 args 之后契约作废,那个节点回退成普通模板。不写契约的话,值里带 `{{ }}` 的文本会在运行时被当模板再解释一遍 + (K01 的二次渲染反例);而模板留在节点上也不行——engine/variables 会把「引用了没人产出的 {{ input.x }}」判成错误, + 那张图跑不起来(拷进的是问数据的图,入口没有口径的入口字段)。""" + if metrics is not None or whole_card: + pinned = select_pinned(pinned, metric_ids=metrics, whole_card=whole_card) rename = {str(n["id"]): f"{prefix}{n['id']}" for n in pinned.fetches} if prefix else {} nodes: list[dict[str, Any]] = [] for original in pinned.fetches: @@ -277,11 +454,22 @@ def caliber_block(pinned: Pinned, *, prefix: str = "", upgrade_policy: str | Non node["id"] = rename.get(str(node["id"]), str(node["id"])) node["position"] = {"x": 0, "y": 0} if inputs is not None and isinstance(node.get("data"), dict): - node["data"]["config"] = render_inputs(node["data"].get("config") or {}, inputs) + config = node["data"].get("config") or {} + template = str(((config.get("args") or {}) if isinstance(config, dict) else {}).get("sql") or "") + node["data"]["config"] = render_inputs(config, inputs) + if params.input_refs(template): + # 契约与渲染好的 args 绑定(rendered):节点被复制、args 改过之后契约自动作废,运行时回退正常渲染 + node["data"]["config"][params.KEY] = params.marker( + rendered=node["data"]["config"].get("args"), template=template, values=inputs, + declared_fields=declared_entry_fields(pinned), + source={**pinned.ref(), "node_id": str(original.get("id") or pinned.node_id)}) nodes.append(node) source = pinned.ref() if rename: source = {**source, "nodes": dict(rename)} + selection = _selection_ids(pinned) + if selection: + source = {**source, "metrics": selection} config: dict[str, Any] = {"caliber_from": source} on_missing = pinned.card_config.get("on_missing") if on_missing not in (None, ""): @@ -293,6 +481,21 @@ def caliber_block(pinned: Pinned, *, prefix: str = "", upgrade_policy: str | Non return Block(nodes=nodes, card_id=card_id, rename=rename, source=pinned.describe()) +def _selection_ids(pinned: Pinned) -> list[str]: + """这一版这次选了哪些指标(按源卡顺序):整卡、或手里没有闭包(手工拼的 Pinned)时是空——那时不写这一项, + 运行时按整卡算,和以前一样。""" + closure = pinned.closure + return [] if closure is None or closure.whole_card else [str(m) for m in closure.metric_ids] + + +def declared_entry_fields(pinned: Pinned) -> tuple[dict[str, Any], ...]: + """写参数契约时记的入口字段:**那一版入口声明了什么**,不随这次选了哪些指标而变。裁剪过(选了指标)的 Pinned 手上 + 只有这次要用的那几个,就从读这一版时留下的图里取回全部;图不在(手工拼的 Pinned)就用手上这份。""" + if pinned.closure is not None and not pinned.closure.whole_card: + return entry_fields(pinned.graph) or pinned.entry_fields + return pinned.entry_fields + + def _free_id(wanted: str, taken: set[str]) -> str: nid, n = wanted, 2 while nid in taken: @@ -355,9 +558,14 @@ def reconcile_prefix(pinned: Pinned) -> str: def ours_block(sql: str, tool: str, *, label: str = "这次的取数") -> Block: - """对账里「这次的取数」:这次执行过的 SQL 原文,放进一个调用工具节点(id ours_q1)。没有口径卡。""" - return Block(nodes=[_node(OURS_ID, "tool", label, tool=tool, args={"sql": sql})], card_id=None, - source={"kind": "executed", "node_id": OURS_ID}) + """对账里「这次的取数」:这次执行过的 SQL 原文,放进一个调用工具节点(id ours_q1)。没有口径卡。 + + 放进节点的**是实际执行过的那条语句,不是模板**:写一份参数契约(ledger/params 的 marker,与这条语句绑定),运行时的 + 模板渲染一概不碰它。不然语句里带 {{ }} 的值(值里就是有这种字)会在运行时被再解释一遍,对账比的就不是这次查过的那条了。""" + return Block(nodes=[_node(OURS_ID, "tool", label, tool=tool, args={"sql": sql}, + **{params.KEY: params.marker(rendered={"sql": sql}, + source={"kind": "executed", "node_id": OURS_ID})})], + card_id=None, source={"kind": "executed", "node_id": OURS_ID}) def reconcile_graph(pinned: Pinned, ours: Block, tail: Sequence[dict[str, Any]], *, @@ -435,6 +643,7 @@ def caliber_probe(pinned: Pinned, *, upgrade_policy: str | None = None) -> Deriv __all__ = ["ALIGN_ID", "Block", "DerivedGraph", "ENTRY_ID", "EXIT_ID", "GONE", "KINDS", "NOT_CARD", "NOT_REUSABLE", - "NotDerivable", "OURS_ID", "Pinned", "RECALL_CARD", "RECONCILE_CARD", "TEMPLATE", "assemble", "caliber_block", - "caliber_probe", "entry_fields", "load_pinned", "ours_block", "recall_fields", "recall_graph", - "recall_prefixes", "reconcile_graph", "reconcile_prefix", "render_inputs", "template_problem"] + "NotDerivable", "OURS_ID", "Pinned", "RECALL_CARD", "RECONCILE_CARD", "SELECTION", "TEMPLATE", "assemble", + "caliber_block", "caliber_probe", "declared_entry_fields", "entry_fields", "load_pinned", "ours_block", + "problems_text", "read_pinned", "recall_fields", "recall_graph", "recall_prefixes", "reconcile_graph", + "reconcile_prefix", "render_inputs", "select_pinned", "template_problem"] diff --git a/backend/app/ledger/descriptor.py b/backend/app/ledger/descriptor.py index b09ee93a..f4f4cb6b 100644 --- a/backend/app/ledger/descriptor.py +++ b/backend/app/ledger/descriptor.py @@ -3,10 +3,15 @@ 口径已经能按固定版本实例化(look/calibers 的查看结果、ledger/compose 的 use_caliber),但入口字段、依赖、能不能出具这些 契约只写在给模型看的文字里。这里把它们写成结构化的数据: -- 只列每个工作流最新「已发布且未退役」版本里的**源头口径卡**(metrics 节点、caliber_from 为空),和 look/calibers、 - ledger/derive 的认法一致:转抄卡不列,源头才能复用; +- 只列每个工作流**推荐发布版**(Workflow.published_version,K07:默认调用读推荐版,不机械取最高已发布版)里的 + **源头口径卡**(metrics 节点、caliber_from 为空),和 look/calibers、ledger/derive 的认法一致:转抄卡不列, + 源头才能复用; - 入口字段用 ledger/derive.entry_fields,按 apps/forms.input_schema 转成 JSON Schema(和表单、use_caliber 校验同一个); - 依赖只从图里的取数节点认数据源和表名,**不返回 SQL、不返回参数值**(SQL 里可能写着遮罩值,组合时由服务端照抄); +- 能不能组合按**每个指标**判(K08 S4,look/calibers.metric_options):B 独有那条查询坏了、绑定对不上,只让 B 不可以选, + A 照旧可组合;一个可选指标也没有才不能组合。另给这一版的两份闭包摘要——``closure``(不点名、整卡那份)与 + ``selectable_metrics`` / ``unavailable_metrics``(每个指标的摘要与原因),以及 ``computes_unselected``(共享 SQL 还在 + 算哪些没选中的指标)。摘要与描述里只有 query_id、字段、工具、指纹这些,**没有 SQL 正文、没有参数值**; - 出具只描述这一版的策略:级别、图里有没有人工节点或写外部系统的节点。全局的自动出具开关、每日上限是运行时条件,这里 不查——descriptor 说的是「这一版允许什么」,不代表这次运行一定能出具。 """ @@ -22,10 +27,8 @@ from app.apps.backfill import graph_side_effect from app.apps.forms import input_schema from app.apps.tree import node_map from app.db.models import Workflow -from app.engine.evidence import sql_tables from app.ledger.derive import entry_fields -from app.look.calibers import card_inputs -from app.tools.datasource import QUERY_PREFIX +from app.look.calibers import metric_options, option_reason #: 指标只写口径卡配置里真有的这几个键 METRIC_KEYS = ("id", "name", "unit", "decimals", "format", "kind", "definition", "params", "external", "rule", @@ -33,16 +36,21 @@ METRIC_KEYS = ("id", "name", "unit", "decimals", "format", "kind", "definition", async def list_calibers(session: AsyncSession, *, workflow_id: str | None = None) -> list[dict[str, Any]]: - """每个工作流最新「已发布且未退役」版本里的源头口径卡,一张卡一条描述。给了 workflow_id 只列那个工作流。 + """每个工作流**推荐发布版**(Workflow.published_version)里的源头口径卡,一张卡一条描述。给了 workflow_id 只列那个工作流。 + + K07:默认调用读的是**推荐版**(重新推上一版旧版之后,默认就跟着它走),不再机械地取「最高已发布版」——最高版 + 只在升级发现里用(app/apps/publications.upgrade_of)。 同一版图里的 graph_side_effect 按 (workflow_id, version) 只算一次:它要读子图、跑发布检查,比其余字段慢得多。""" + from app.apps import publications + query = select(Workflow).order_by(Workflow.name, Workflow.id) if workflow_id: query = query.where(Workflow.id == workflow_id) side_cache: dict[tuple[str, int], str | None] = {} out: list[dict[str, Any]] = [] for workflow in (await session.execute(query)).scalars().all(): - row = await app_versions.latest_published(session, workflow.id) + row = await publications.recommended(session, workflow) if row is None: continue for node_id, node in node_map(row.graph or {}).items(): @@ -76,25 +84,16 @@ async def _describe(session: AsyncSession, workflow: Workflow, row: Any, node_id return None cfg = card["config"] level = str(row.level or "") - _, reason = card_inputs(graph, node_id) - if reason is None: - from app.ledger.derive import template_problem - - for nid, node in nodes.items(): - tool = str((node.get("config") or {}).get("tool") or "") - sql = ((node.get("config") or {}).get("args") or {}).get("sql") \ - if isinstance((node.get("config") or {}).get("args"), dict) else None - if node.get("type") == "tool" and tool.startswith(QUERY_PREFIX) and isinstance(sql, str) and sql.strip(): - if problem := template_problem(str(nid), node.get("config") or {}): - reason = problem - break + made = metric_options(graph, node_id, workflow_id=workflow.id, version=int(row.version)) + from app.apps import publications from app.data.caliber_identity import semantic_hash key = (workflow.id, int(row.version)) if key not in side_cache: side_cache[key] = await graph_side_effect(session, graph, level=level or None) side_effect = side_cache[key] - sources, tables = _fetches(nodes) + sources, tables = publications.fetch_dependencies(graph) + publication = await publications.latest(session, workflow.id, int(row.version)) reasons: list[str] = [] if level != "governed": reasons.append("这一版是已发布级别,只支持一键出具") @@ -109,37 +108,48 @@ async def _describe(session: AsyncSession, workflow: Workflow, row: Any, node_id "level": level, "graph_hash": row.graph_hash, "semantic_hash": semantic_hash(graph, node_id), + # K07:这一版的发布依据是哪一份清单(没有清单的是加这一机制之前发布的老资产,值为 null) + "publication": ({"id": publication.id, "manifest": publication.manifest, + "proven": bool(publication.proven)} + if publication is not None else None), "card": {"node_id": node_id, "title": card["title"], "caliber": cfg.get("caliber"), "caliber_version": cfg.get("caliber_version")}, "metrics": [{k: m[k] for k in METRIC_KEYS if k in m} for m in cfg.get("metrics") or [] if isinstance(m, dict) and m.get("id")], "entry_schema": input_schema(list(entry_fields(graph))), - "composable": reason is None, - "compose_reason": reason, - "dependencies": {"sources": sorted(sources), "tables": sorted(tables), + # 能不能组合按**每个指标**判(K08 S4):B 独有那条查询坏了、绑定对不上,A 照旧可选;一个指标也选不了才不能组合。 + # 摘要里只有 query_id、字段、工具、指纹与共享声明,没有 SQL 正文、没有参数值 + "composable": made.composable, + "compose_reason": option_reason(made), + "closure": made.default, + "selectable_metrics": [dict(m) for m in made.selectable], + "unavailable_metrics": [dict(m) for m in made.unavailable], + "computes_unselected": shared_queries(made), + "dependencies": {"sources": sources, "tables": tables, "catalog_versions": row.catalog_versions, "schema_versions": row.schema_versions}, "issuance": {"level": level, "auto_issue": level == "governed" and side_effect is None and bool(sources), "requires_independent_proof": True, "side_effects": side_effect, "reasons": reasons}, } -def _fetches(nodes: dict[str, dict[str, Any]]) -> tuple[set[str], set[str]]: - """图里调用数据库查询工具、而且写了 SQL 的节点:数据源名、SQL 里 FROM / JOIN 的表名(去库名前缀)。只认表名,不读 SQL。""" - sources: set[str] = set() - tables: set[str] = set() - for node in nodes.values(): - if node["type"] != "tool": - continue - tool = str(node["config"].get("tool") or "") - args = node["config"].get("args") - sql = args.get("sql") if isinstance(args, dict) else None - # 工具名带模板的不是固定的数据源,认不出「哪一版库」 - if not tool.startswith(QUERY_PREFIX) or "{{" in tool or not isinstance(sql, str) or not sql.strip(): - continue - sources.add(tool[len(QUERY_PREFIX):]) - tables.update(t.rsplit(".", 1)[-1] for t in sql_tables(sql)) - return sources, tables +def shared_queries(made: Any) -> list[dict[str, Any]]: + """这几份摘要里「还在算没选中的指标」的查询:{query_id, node_id, metric_ids, computes_unselected}。 + + 按 (query_id, 这次选中的指标) 去重、按出现先后排:一张卡上几个指标共用一条 SQL 时,选谁、还在算谁一目了然(K08 S3 + 不做投影,共享 SQL 原样保留)。整卡那一份加上每个可选指标那一份,只从闭包的摘要里收,不另解析一遍依赖。""" + out: list[dict[str, Any]] = [] + seen: set[tuple[str, tuple[str, ...]]] = set() + for summary in [made.default, *made.selectable]: + for query in (summary or {}).get("queries") or []: + others = [str(m) for m in query.get("computes_unselected") or []] + read_by = [str(m) for m in query.get("metric_ids") or []] + if not others or (str(query["query_id"]), tuple(read_by)) in seen: + continue + seen.add((str(query["query_id"]), tuple(read_by))) + out.append({"query_id": query["query_id"], "node_id": query["node_id"], + "metric_ids": read_by, "computes_unselected": others}) + return out -__all__ = ["caliber_descriptor", "list_calibers"] +__all__ = ["caliber_descriptor", "list_calibers", "shared_queries"] diff --git a/backend/app/ledger/docdraft.py b/backend/app/ledger/docdraft.py index 024b2936..57f7af71 100644 --- a/backend/app/ledger/docdraft.py +++ b/backend/app/ledger/docdraft.py @@ -17,10 +17,13 @@ from __future__ import annotations import copy import json +import logging import re from collections.abc import Iterable, Mapping from typing import Any +logger = logging.getLogger(__name__) + #: 草稿的状态(机器判别的落点,接口按它返回)。界面上只看得到四种阶段(STAGES):草稿在写、待审、已丢弃、失败。 #: ready 是主路径的常态:图已生成(含取数 SQL)、没有未决问题、可试跑可签字发布;questions_open 有图也有数,只是问题 #: 还没清完(不阻断试跑);path_pending 留给这次改版之前起草、还没有取数路径的老草稿;attached 是经辅助入口接上一次 @@ -46,6 +49,15 @@ MAX_INPUT_CHARS = 40000 #: 引用归一化之后少于这么多字,说明它指不出一句完整的话,丢掉 MIN_QUOTE_CHARS = 8 +#: 来源快照的工件种类与格式版本(存进 app/core/artifact_store 的内容寻址工件)。名字不带 source_snapshots: +#: 那是数据源上传快照的表(app/db/models.SourceSnapshot),和「一次抽取读到的文档材料」不是一回事。 +SNAPSHOT_KIND = "caliber_source_snapshot" +SNAPSHOT_VERSION = 1 +#: 抽取提示词的版本。改了 _SYSTEM(怎么抽、要求怎么写引用)就 +1:草稿里记下这一版,历史结果才知道是按哪一版抽的。 +PROMPT_VERSION = 1 +#: 解析与归一化的版本。改了 parse_reply / normalize_metrics(引用核对、字段清洗的规则)就 +1。 +PARSE_VERSION = 1 + #: 指标对象里固定出现的字段(提示词和归一化都按这一份) METRIC_FIELDS = ("name", "synonyms", "unit", "grain", "time_field", "filters", "numerator", "denominator", "dimensions", "definition", "open_questions") @@ -415,10 +427,13 @@ def _fit(docs: list[dict], chunks: dict[str, dict], guidance: str, async def extract(session: Any, *, docs: list[dict], chunks: dict[str, dict], guidance: str = "", datasource: dict | None = None, model: Any = None) -> dict: - """一次模型调用,返回 {"metrics", "dropped", "open_questions", "truncated", "model_id"}。 + """一次模型调用,返回 {"metrics", "dropped", "open_questions", "truncated", "model_id", + "visible_chunk_ids", "prompt_version", "parse_version"}。 不落库。model 可注入(测试用假对象:有 async ainvoke(messages),回复有 .content);不给就按设置解析, 模型不可用时抛 DraftUnavailable,reason 原样给人看。输入超限按 chunk 截断,truncated 交调用方在界面上说清楚。 + visible_chunk_ids 是**实际进了这次提示**的段落(按 ordinal 排):被 _fit 丢掉的段落不在里面,引用它也核不上—— + 引用核对只认实际可见的材料,核对用的正是这里交出去的这一份。 """ from app.engine.state import message_text @@ -450,6 +465,9 @@ async def extract(session: Any, *, docs: list[dict], chunks: dict[str, dict], gu "open_questions": questions if isinstance(questions, list) else [], "truncated": truncated, "model_id": model_id, + "visible_chunk_ids": _order(kept), + "prompt_version": PROMPT_VERSION, + "parse_version": PARSE_VERSION, } @@ -597,8 +615,99 @@ def merge_definition(card_metrics: list[dict], draft_metrics: list[dict]) -> tup salvage_metrics = _salvage_metrics +# ========================================================================== +# 来源快照(K05:提取那一刻就把原文和材料存下来,草稿只记引用) +# ========================================================================== + + +def source_snapshot(*, documents: list[Any], chunks: Mapping[str, Any], datasource: Any = None, + catalog: str = "", guidance: str = "", fixed_filters: str = "") -> dict: + """把这次抽取实际读到的来源材料收成一份**可还原**的快照:逐份原文、逐段原文,以及会改变模型看到什么的那几样 + (数据目录文本、用户补充要求、固定条件、数据源)。调用方把它存进 app/core/artifact_store,草稿里只记返回的 id。 + + **为什么不能只存哈希。** 哈希只说明「还是那一份」,说不出内容是什么;重导入要比对的是「上次被接受的导入值」 + (任务书 B),只有哈希就还原不了 B。所以原文整份进快照,chunk 的可见单位就是段。 + + **为什么按内容寻址。** 同一份材料只存一份,工件 id 就是规范化 JSON 的 sha256;快照因此不可变,也不会因为草稿 + 后来被改而跟着变。文档被重新切块、chunk id 换了一批,这份快照照旧读得回来(它按 id 认内容,不按名字)。 + + **这不是字段基线。** 快照只保证「当时的材料还原得出来」,字段级的 B 要等接受重导入时按字段推进(见 K11)。 + """ + from app.core.artifact_store import content_hash + + def text(value: Any) -> str: + return value if isinstance(value, str) else "" + + docs: list[dict[str, Any]] = [] + for doc in documents if isinstance(documents, list) else []: + item = doc if isinstance(doc, Mapping) else {} + content = text(item.get("content")) + docs.append({"document_id": str(item.get("document_id") or item.get("id") or ""), + "title": text(item.get("title")), "source": text(item.get("source")), + "collection": text(item.get("collection")), + "content": content, "content_hash": content_hash(content)}) + kept: dict[str, dict[str, Any]] = {} + for chunk_id, chunk in (chunks if isinstance(chunks, Mapping) else {}).items(): + item = chunk if isinstance(chunk, Mapping) else {} + content = text(item.get("content")) + ordinal = item.get("ordinal") + kept[str(chunk_id)] = {"document_id": str(item.get("document_id") or ""), + "ordinal": ordinal if isinstance(ordinal, int) else None, + "content": content, "content_hash": content_hash(content)} + return {"kind": SNAPSHOT_KIND, "version": SNAPSHOT_VERSION, "documents": docs, "chunks": kept, + "datasource": dict(datasource) if isinstance(datasource, Mapping) else None, + "catalog": text(catalog), "guidance": text(guidance), "fixed_filters": text(fixed_filters)} + + +def snapshot_ref(artifact_id: str, snapshot: Mapping[str, Any]) -> dict: + """草稿 payload 里放的那一份引用:工件 id(= 内容的 sha256)、格式版本、这份快照收了哪些文档和段落。 + + 原文不在 payload 里再抄一遍——草稿页按这份引用回工件库读,读到的是当初那一份,不会随草稿改动。 + """ + return {"artifact_id": str(artifact_id or ""), "kind": snapshot.get("kind") or SNAPSHOT_KIND, + "version": snapshot.get("version") or SNAPSHOT_VERSION, "content_hash": str(artifact_id or ""), + "documents": [str(d.get("document_id")) for d in snapshot.get("documents") or [] + if isinstance(d, Mapping)], + "chunk_ids": sorted(str(c) for c in (snapshot.get("chunks") or {}))} + + +def source_baseline(payload: Any) -> dict[str, Any]: + """这份草稿的来源基线是什么状态:known(有**读得回来**的来源快照)/ baseline_unknown(没有,或读不回来)。 + + **旧草稿一律 baseline_unknown。** 保存来源快照之前起草的草稿没有这份引用,它当时的导入内容是什么已经无法 + 还原;不能拿它现在的内容冒充历史基线(B 是「上次被接受的导入值」,不是「现在长什么样」)。这份引用也不是 + 字段基线——字段级 B 要等接受重导入时按字段落(K11)。 + + **有引用不等于有基线。** 这里会把工件真的读一遍(load 会复验哈希):工件不在、内容被改过、或种类不对,都照实 + 说 baseline_unknown 并把 readable 标成 false——「快照坏了」不能报成 known,也不能在读草稿时抛出去把页面弄崩。 + 读的时候现算,不拿 payload 里存过的那份状态:改了口径内容不改变来源快照,但工件被删被改必须看得出来。 + """ + ref = payload.get("source_snapshot") if isinstance(payload, Mapping) else None + artifact_id = ref.get("artifact_id") if isinstance(ref, Mapping) else None + if not (isinstance(artifact_id, str) and artifact_id): + return {"status": "baseline_unknown", "readable": False, + "reason": "这份草稿没有可还原的来源快照(保存快照之前起草的,或这次落库失败):当时的导入内容无法还原," + "不能拿当前内容当作历史基线"} + try: + from app.core.artifact_store import load + + snapshot = load(artifact_id) + except Exception as e: # noqa: BLE001 - 工件被改过(哈希不符)也算读不出来,照实说,不让读草稿失败 + logger.warning("来源快照工件读不出来(%s):%s", artifact_id, e) + snapshot = None + if not isinstance(snapshot, Mapping) or snapshot.get("kind") != SNAPSHOT_KIND: + return {"status": "baseline_unknown", "readable": False, "artifact_id": artifact_id, + "version": ref.get("version") or SNAPSHOT_VERSION, + "reason": "来源快照工件读不回来(不在、内容与哈希不符,或不是来源快照):当时的导入内容无法还原," + "不能拿当前内容当作历史基线"} + return {"status": "known", "readable": True, "artifact_id": artifact_id, + "version": ref.get("version") or SNAPSHOT_VERSION, + "chunk_ids": sorted(str(c) for c in (snapshot.get("chunks") or {}))} + + __all__ = [ "DEFINITION_FIELDS", "DraftUnavailable", "FORBIDDEN_FIELDS", "MAX_INPUT_CHARS", "METRIC_FIELDS", - "MIN_QUOTE_CHARS", "STAGES", "STATUSES", "alignment", "extract", "merge_definition", "normalize_metrics", - "parse_reply", "prompt", "salvage_metrics", "stage_of", "verify_quote", + "MIN_QUOTE_CHARS", "PARSE_VERSION", "PROMPT_VERSION", "SNAPSHOT_KIND", "SNAPSHOT_VERSION", "STAGES", + "STATUSES", "alignment", "extract", "merge_definition", "normalize_metrics", "parse_reply", "prompt", + "salvage_metrics", "snapshot_ref", "source_baseline", "source_snapshot", "stage_of", "verify_quote", ] diff --git a/backend/app/ledger/draftplan.py b/backend/app/ledger/draftplan.py index 4a123b32..cb17e199 100644 --- a/backend/app/ledger/draftplan.py +++ b/backend/app/ledger/draftplan.py @@ -17,8 +17,9 @@ SELECT,服务端把 SQL、入口字段、口径卡、报告串成图,后台 就没有值,图能建但出不了数。 **为什么 build_graph 收多组 blocks。** 一张草稿图原来只能挂一条 SQL,业务文档几十条指标得分几十次起草、几十张图。取数 -节点多几个、口径卡读全部,试跑一次就跑完;入口字段按 name 合并,同名但类型/必填对不上就抛 ValueError——那是两份草案自己 -打架,调用方当成问题记下来,比悄悄取一个更能让人发现。 +节点多几个、口径卡读全部,试跑一次就跑完;入口字段按 name 合并,必填取并集、类型按一条固定的合并规则定(见 _merged_type, +结果与各组先后无关),默认值冲突就清掉默认值要求人填。不抛错、也不悄悄取某一组:不一致的地方记进 entry_notes 摆给起草的 +人看(早先这里抛 ValueError,一份 34 条指标的草稿因为一个字段的 required 不同就整份作废)。 **为什么引用核对还是照 docdraft 的老规矩。** 定义的事实来源还是文档原文。模型转述得再像,也要能在原文里逐字定位;一条 引用都核不上的指标整条丢弃,写进 problems 交给人看。这里只做校验,不改 docdraft 的规则。 @@ -40,6 +41,8 @@ MAX_INPUT_CHARS = docdraft.MAX_INPUT_CHARS MAX_TABLES_CHARS = 24000 #: 取数 SQL 的长度上限(字符)。再长的查询不是草稿该承载的 MAX_SQL_CHARS = 20000 +#: 这一版提示词的版本(改了 _SYSTEM 就 +1)。写进草稿的提示记录,历史结果才知道是按哪一版起草的。 +PROMPT_VERSION = 1 #: 入口字段能写的类型(apps/spec.FORM_TYPES 的子集;日期用 string + description 说清) ENTRY_TYPES = ("string", "number", "integer", "boolean") @@ -189,15 +192,19 @@ def _chars(messages: list[Any]) -> int: return sum(len(str(getattr(message, "content", "") or "")) for message in messages) -def _fit(docs: list[dict], chunks: dict[str, dict], guidance: str, - datasource: dict | None, tables_text: str, - covered: Sequence[str] = (), fixed: str = "") -> tuple[dict[str, dict], str, bool, bool]: +def fit_material(docs: list[dict], chunks: dict[str, dict], guidance: str, + datasource: dict | None, tables_text: str, + covered: Sequence[str] = (), fixed: str = "") -> tuple[dict[str, dict], str, bool, bool]: """把材料压到 MAX_INPUT_CHARS 以内:先截表目录尾部,再从后往前按 chunk 边界丢,最后截仅剩的那一段。 + 返回 (真正进提示的 chunk, 真正进提示的目录, doc_truncated, catalog_truncated)。 表目录先截:SQL 必须写在目录里的表上,目录比文档的细枝末节更硬;被截掉的是表详情,表名索引还在最前面。 截断来源分开报:doc_truncated 是文档段落被丢/被截,catalog_truncated 是表目录被截。调用方要能说清「指标没覆盖 完,是因为原文没给全,还是因为目录没给全」——改文档、改目录是两件不同的事。 + + **返回值就是「模型实际看到的材料」。** 调用方拿它去核对引用(不能引用被丢掉的段落)、记进提示记录;也可以自己 + 先算一次、把结果传回 plan / plan_groups / repair_group,免得同一份材料在两处各算一遍、算得不一样。 """ kept = dict(chunks) tables = tables_text @@ -264,12 +271,15 @@ def _salvage_reply(text: str) -> dict: async def plan(session: Any, *, docs: list[dict], chunks: dict[str, dict], guidance: str = "", datasource: dict | None = None, tables_text: str = "", model: Any = None, - covered: Sequence[str] = (), fixed: str = "") -> dict: + covered: Sequence[str] = (), fixed: str = "", + fitted: tuple[dict[str, dict], str, bool, bool] | None = None) -> dict: """一次模型调用,返回 {entry_fields, sql, metrics, open_questions, model_id, doc_truncated, - catalog_truncated, truncated}(未校验)。 + catalog_truncated, truncated, visible_chunk_ids, prompt_version, parse_version}(未校验)。 covered 是前几轮已经起草过的指标名,写进提示词让模型不要重复;fixed 是「每次都不变的条件」(工厂、产线、 属性组),提示词要求它写死在 sql 里、不做成入口字段。调用方按 uncovered 续跑,直到 covered 不再增长。 + 截断情况与 visible_chunk_ids 说的是同一份材料:**实际进了这次提示的**那几段,被 fit_material 丢掉的段落不在里面, + 引用它也核不上。fitted 是调用方先算好的材料(fit_material 的返回值),给了就用它,不给这里自己算。 truncated 仍是两者的「或」,老前端只认这一个键。不落库。model 可注入(测试用假对象:有 async ainvoke(messages), 回复有 .content);不给就按设置解析,模型不可用时抛 docdraft.DraftUnavailable。SQL 的对错、引用能不能核对,交给 normalize_plan。 @@ -286,8 +296,9 @@ async def plan(session: Any, *, docs: list[dict], chunks: dict[str, dict], guida named = getattr(model, "model_name", None) or getattr(model, "model", None) model_id = named if isinstance(named, str) else "" - kept, tables, doc_truncated, catalog_truncated = _fit(docs, chunks, guidance, datasource, tables_text, - covered, fixed) + if fitted is None: + fitted = fit_material(docs, chunks, guidance, datasource, tables_text, covered, fixed) + kept, tables, doc_truncated, catalog_truncated = fitted reply = await model.ainvoke(prompt(docs, kept, guidance, datasource, tables, covered, fixed)) text = message_text(reply) salvaged = False @@ -320,6 +331,9 @@ async def plan(session: Any, *, docs: list[dict], chunks: dict[str, dict], guida "salvaged": salvaged, "diagnostics": diagnostics, "model_id": model_id, + "visible_chunk_ids": _order(kept), + "prompt_version": PROMPT_VERSION, + "parse_version": docdraft.PARSE_VERSION, "doc_truncated": doc_truncated, "catalog_truncated": catalog_truncated, "truncated": doc_truncated or catalog_truncated, @@ -341,12 +355,17 @@ def _reply_groups(data: Mapping) -> list[dict]: async def plan_groups(session: Any, *, docs: list[dict], chunks: dict[str, dict], guidance: str = "", datasource: dict | None = None, tables_text: str = "", model: Any = None, - covered: Sequence[str] = (), fixed: str = "") -> dict: - """一次模型调用,交回**多组**草案(未校验):{groups, open_questions, uncovered, model_id, ...}。 + covered: Sequence[str] = (), fixed: str = "", + fitted: tuple[dict[str, dict], str, bool, bool] | None = None) -> dict: + """一次模型调用,交回**多组**草案(未校验):{groups, open_questions, uncovered, model_id, + visible_chunk_ids, prompt_version, parse_version, ...}。 和 plan() 的区别只在输出形状:模型一次尽量交几组「能共用一条 SQL 的指标」,剩下的写 uncovered;调用方不必为一组 指标各调一次模型。每组的结构仍是 {sql, entry_fields, metrics},交给 normalize_plan 逐组校验;一组不合格只丢那一组, 不影响别的组。旧形状(顶层 sql + metrics)也收,当成只有一组——模型不按新格式回时不用整份作废。 + + fitted 是调用方先算好的材料(fit_material 的返回值)。给了就用它,调用方由此知道自己看到的 visible_chunk_ids + 与实际提示一致,不必再算一遍;不给这里自己算(其它入口照旧)。 """ from app.engine.state import message_text @@ -360,8 +379,9 @@ async def plan_groups(session: Any, *, docs: list[dict], chunks: dict[str, dict] named = getattr(model, "model_name", None) or getattr(model, "model", None) model_id = named if isinstance(named, str) else "" - kept, tables, doc_truncated, catalog_truncated = _fit(docs, chunks, guidance, datasource, tables_text, - covered, fixed) + if fitted is None: + fitted = fit_material(docs, chunks, guidance, datasource, tables_text, covered, fixed) + kept, tables, doc_truncated, catalog_truncated = fitted reply = await model.ainvoke(prompt(docs, kept, guidance, datasource, tables, covered, fixed)) text = message_text(reply) salvaged = False @@ -392,6 +412,9 @@ async def plan_groups(session: Any, *, docs: list[dict], chunks: dict[str, dict] "salvaged": salvaged, "diagnostics": diagnostics, "model_id": model_id, + "visible_chunk_ids": _order(kept), + "prompt_version": PROMPT_VERSION, + "parse_version": docdraft.PARSE_VERSION, "doc_truncated": doc_truncated, "catalog_truncated": catalog_truncated, "truncated": doc_truncated or catalog_truncated, @@ -400,10 +423,13 @@ async def plan_groups(session: Any, *, docs: list[dict], chunks: dict[str, dict] async def repair_group(session: Any, *, group: Mapping, problems: list[dict], docs: list[dict], chunks: dict[str, dict], guidance: str = "", datasource: dict | None = None, - tables_text: str = "", model: Any = None, fixed: str = "") -> dict: + tables_text: str = "", model: Any = None, fixed: str = "", + fitted: tuple[dict[str, dict], str, bool, bool] | None = None) -> dict: """只重写一组:把这一组原来的指标和没通过校验的原因交回模型,返回修好的原始组(未校验)。 修不出来返回 {},由调用方照实记失败,不让整份草稿跟着作废。修的时候只给这一组的指标名和问题,不让模型重排别的组。 + fitted 是调用方先算好的材料(fit_material 的返回值,与本次提示一致)。给了就用它,引用核对与本轮其它调用用同一份 + 可见材料;不给这里自己算。 """ from app.engine.state import message_text @@ -413,8 +439,9 @@ async def repair_group(session: Any, *, group: Mapping, problems: list[dict], do model, _model_id, availability = await resolve_draft_model(session) if model is None or not getattr(availability, "available", False): raise docdraft.DraftUnavailable(getattr(availability, "reason", "") or "AI 起草不可用") - kept, tables, _doc_truncated, _catalog_truncated = _fit(docs, chunks, guidance, datasource, tables_text, - (), fixed) + if fitted is None: + fitted = fit_material(docs, chunks, guidance, datasource, tables_text, (), fixed) + kept, tables = fitted[0], fitted[1] names = [str(metric.get("name") or metric.get("id")) for metric in group.get("metrics") or [] if isinstance(metric, Mapping) and (metric.get("name") or metric.get("id"))] reasons = ";".join(f"{problem.get('name') or '问题'}:{problem.get('reason') or ''}" @@ -433,6 +460,13 @@ async def repair_group(session: Any, *, group: Mapping, problems: list[dict], do return groups[0] if groups else {} +def _entry_type(value: Any) -> str: + """入口字段声明的类型规范成 ENTRY_TYPES 里的一个词:认不出的按文字(apps.forms.input_schema 也按同一套认)。 + + 起草时(_entry_fields)和合并各组声明时(_merged_type)用同一份判断:这套写法从哪个入口进来,认出来的都是同一个词。""" + return value if value in ENTRY_TYPES else "string" + + def _entry_fields(value: Any, problems: list[dict]) -> list[dict]: """入口字段归一化:名字必填、不重名;类型落回能认的几种,认不出的按文字。""" out: list[dict] = [] @@ -450,9 +484,7 @@ def _entry_fields(value: Any, problems: list[dict]) -> list[dict]: problems.append({"name": name, "reason": "入口字段重名"}) continue seen.add(name) - kind = item.get("type") - if kind not in ENTRY_TYPES: - kind = "string" + kind = _entry_type(item.get("type")) default = item.get("default") if not isinstance(default, (str, int, float, bool)): default = None @@ -648,12 +680,25 @@ def _blocks(value: Any) -> list[dict]: return [dict(block) for block in value or [] if isinstance(block, Mapping)] +def _merged_type(left: str, right: str) -> str: + """两组把同一个入口字段声明成不同(已规范的)类型时,合并成什么:两边对调结果一样,与哪一组先出现无关(R02)。 + + - 整数和数都是数(records.store.union_compatible 也把这两类算一列):并成数——数能填小数,能把整数那一组的值收下, + 反过来 3.5 会被「整数」拒收; + - 别的组合一律并成文字:文字跟谁都能并;是或否和数/整数不能互相表示(true 不是 1),退回文字让人填,不拿某一组的 + 说法去判另一组的值。合并结果永远落在 ENTRY_TYPES 里。""" + if left == right: + return left + return "number" if {left, right} <= {"number", "integer"} else "string" + + def _merge_fields(target: dict[str, dict], value: Any, notes: list[str], conflicts: set[str]) -> None: """入口字段按 name 合并,冲突取更保守的一边,**不抛错**。 同一份文档分几轮起草,各组对同一个字段的声明常常对不上:一组说必填、另一组给了缺省;一组按数、另一组按文本。 - 这不是错误——它们本来就是从不同批指标里各看了一次。合并时必填取并集(有一组要就必须给),类型取更宽的一个 - (能填进文本)。默认值冲突时清掉默认值、要求人填,不能自动把某一组的范围用于其他组;0 和 False 都是有效值。 + 这不是错误——它们本来就是从不同批指标里各看了一次。合并时必填取并集(有一组要就必须给),类型按 _merged_type 的 + 规则定(数+整数并成数,别的并成文字,结果与各组先后无关)。默认值冲突时清掉默认值、要求人填,不能自动把某一组 + 的范围用于其他组;0 和 False 都是有效值。 早先这里抛 ValueError,结果一份 34 条指标的草稿因为一个字段的 required 不同就整份作废——代价完全不成比例。 """ @@ -665,15 +710,15 @@ def _merge_fields(target: dict[str, dict], value: Any, notes: list[str], conflic continue item = dict(field) item["name"] = name + item["type"] = _entry_type(item.get("type")) old = target.get(name) if old is None: target[name] = item continue merged = dict(old) - old_type = str(old.get("type") or "string") - new_type = str(item.get("type") or "string") + old_type, new_type = _entry_type(old.get("type")), item["type"] + merged["type"] = _merged_type(old_type, new_type) if old_type != new_type: - merged["type"] = "string" if "string" in (old_type, new_type) else old_type notes.append(f"入口字段「{name}」在各组里的类型不一致({old_type} / {new_type}),按「{merged['type']}」合并") if bool(old.get("required")) != bool(item.get("required")): merged["required"] = bool(old.get("required")) or bool(item.get("required")) @@ -799,4 +844,5 @@ def build_graph(blocks: Any, *, name: str, question: str = "", datasource: str = __all__ = ["ENTRY_TYPES", "MAX_INPUT_CHARS", "MAX_SQL_CHARS", "MAX_TABLES_CHARS", "METRIC_FIELDS", - "build_graph", "normalize_plan", "plan", "plan_groups", "prompt", "repair_group", "unique_metric_ids"] + "PROMPT_VERSION", "build_graph", "fit_material", "normalize_plan", "plan", "plan_groups", + "prompt", "repair_group", "unique_metric_ids"] diff --git a/backend/app/ledger/fieldbaseline.py b/backend/app/ledger/fieldbaseline.py new file mode 100644 index 00000000..d21e449e --- /dev/null +++ b/backend/app/ledger/fieldbaseline.py @@ -0,0 +1,402 @@ +"""字段基线 B(K05):**首次接受导入**那一刻被接受的字段值,按 metric_id + field_path 存成不可变工件。 + +**B / L / R 是三个东西。** + +- **B**(baseline)是「上一次被接受的导入值」:导入被接受、写进初始草稿图的那一份。它只由「接受一次导入」推进, + 不随人工编辑变。这份取值只从**当时落进图里的值**取,不拿草稿现在长什么样倒填历史。 +- **L**(live)是当前人工维护的内容:画布和草稿页上的字段操作(K03 的 operations)、整份换指标,改的都是 L。 + 改 L 一个字都不动 B。 +- **R**(re-import candidate)是新导入的候选,K11 才做;这里只把 B 存下来,让那时候有真基线可比。 + +**为什么是工件不是一张表。** B 是一份「当时是什么」的只读材料:按内容寻址存进 app/core/artifact_store,草稿 payload +只记一份引用(id + 版本 + 收了哪些指标、几个字段)。工件不可变、同一份材料只存一次,读的时候复验哈希——够用, +不用另建一套文档版本平台。 + +**为什么不能只存哈希。** 哈希只说明「还是那一份」,说不出内容是什么;重导入要比对的是值本身(哪个字段、被接受成 +什么、对应哪段原文)。所以工件里**逐字段存值**(数组、引用照原样),每一格另带自己的值哈希。 + +**旧资产一律 baseline_unknown。** 保存基线之前建的草稿没有这份引用:当时的导入值是什么已经无法还原,不能拿它 +现在的内容冒充 B(见 status_of)。工件在、但读不回来(被删掉,或内容与哈希不符)同样算 baseline_unknown, +readable=false:**有引用不等于真的有基线**,也不能在读草稿时把它报成 known。字段级 B 也是「按字段推进」的前提: +只有 accepted_revision 记着它是在哪一版被接受的。 + +**known 不等于完整(coverage)。** 首次接受导入收的是整张卡,逐格都有值,覆盖是 complete。之后按字段推进 +(K11 的 advance)常常只覆盖卡上的一部分:`coverage.status` 因此是 partial,另附每条指标覆盖了几格、还缺哪些格、 +哪几条指标整条没有基线。**不能因为有一份读得回来的 B 就把整张卡说成完整 known**——有没有基线看 status, +是不是整张都有看 coverage。 +""" +from __future__ import annotations + +import logging +from collections.abc import Iterable, Mapping +from typing import Any + +logger = logging.getLogger(__name__) + +#: 字段基线工件在工件库里的种类与格式版本 +KIND = "caliber_field_baseline" +VERSION = 1 +#: B 里除了「能按字段改的那些」之外另收的一项:引用原文是导入接受值的一部分(证据归属,改不了但要有基线) +CITATIONS_FIELD = "/definition/citations" + +#: payload 里放引用的键(当前 B)和它的历史(每次接受导入追加一条) +REF_KEY = "field_baseline" +HISTORY_KEY = "field_baseline_history" + + +def accepted_card(graph: Any) -> tuple[str, list[dict[str, Any]]]: + """这份图里「这次被接受的导入」落在哪张卡上:(card_id, 卡上的指标)。 + + 认法和读接口的权威卡一致(见 app/api/ledger.py 的 editable_cards / draft_card):只认源头口径卡 + (metrics 节点、没有 caliber_from);只有一张时就是它,多张时优先下游契约声明的那一张(contract.metrics_from + 只写了一张),都认不出时取第一张可写的。一张都没有时 ("", [])——调用方据此照实说没有基线,不猜。 + """ + cards: list[tuple[str, list[dict[str, Any]]]] = [] + referenced = "" + for node in (graph or {}).get("nodes") or []: + if not isinstance(node, Mapping): + continue + config = (node.get("data") or {}).get("config") if isinstance(node.get("data"), Mapping) else None + config = config if isinstance(config, Mapping) else {} + if node.get("type") == "metrics" and config.get("caliber_from") in (None, "", {}): + metrics = [dict(m) for m in config.get("metrics") or [] if isinstance(m, Mapping) and m.get("id")] + cards.append((str(node.get("id") or ""), metrics)) + contract = config.get("contract") + sources = contract.get("metrics_from") if isinstance(contract, Mapping) else None + ids = [sources] if isinstance(sources, str) else [s for s in sources or [] if isinstance(s, str)] + if len(ids) == 1: + referenced = ids[0] + if not cards: + return "", [] + for card_id, metrics in cards: + if referenced and card_id == referenced: + return card_id, metrics + return cards[0] + + +def field_paths() -> tuple[str, ...]: + """按字段记 B 时收哪些路径:能按字段改的那一套(K03 的白名单,和界面同一份)+ 引用原文。 + + 直接取 `app/ledger/changes.FIELDS` 的键,不在这儿另抄一份——两处一旦漂移,人工改得动的字段和记了基线的字段 + 就对不上了。排序只为了让同一份材料每次都长成同一个规范 JSON。 + """ + from app.ledger import changes + + return (*sorted(changes.FIELDS), CITATIONS_FIELD) + + +def value_at(metric: Any, path: str) -> Any: + """一条指标上某个字段路径的值;路径上没有这个键时抛 KeyError(调用方按「没这个字段」处理)。""" + if not isinstance(metric, Mapping): + raise KeyError(path) + segments = [segment for segment in str(path).split("/") if segment] + node: Any = metric + for segment in segments: + if not isinstance(node, Mapping) or segment not in node: + raise KeyError(path) + node = node[segment] + return node + + +def fields_of(metric: Any, *, paths: Iterable[str] | None = None) -> dict[str, dict[str, Any]]: + """一条指标被接受的字段值:{field_path: {"value": …, "hash": …}}。 + + 没有这个字段就不写进去(「没声明」和「值是空」是两件事,见 changes 的四种写法)。值原样深拷贝一份: + 数组、引用(citations 里的 chunk/document_id/quote/span)都按当时的样子留着,重导入要有东西可比。 + """ + import copy + + from app.core.artifact_store import canonical_json, content_hash + + wanted = tuple(paths) if paths is not None else field_paths() + out: dict[str, dict[str, Any]] = {} + for path in wanted: + try: + value = value_at(metric, path) + except KeyError: + continue + kept = copy.deepcopy(value) + out[path] = {"value": kept, "hash": content_hash(canonical_json(kept))} + return out + + +def document(*, metrics: Iterable[Any], card_id: str, workflow_id: str, accepted_revision: int, + source_snapshot: Mapping[str, Any] | None = None, accepted_at: str = "", + accepted_by: str | None = None) -> dict[str, Any]: + """一份字段基线工件的内容:逐指标的逐字段值 + 它是在哪一版被接受的 + 来源快照引用。 + + 只收被接受进图里的那份指标(调用方传图上的指标),不收草稿现在的内容;`source_snapshot` 是抽取那一刻存的 + 来源快照引用(docdraft.snapshot_ref)——B 和它连着,将来重导入要拿它还原当时的原文。 + """ + items: dict[str, Any] = {} + metric_ids: list[str] = [] + total = 0 + for metric in metrics if isinstance(metrics, (list, tuple)) else []: + if not isinstance(metric, Mapping): + continue + metric_id = str(metric.get("id") or "").strip() + if not metric_id: + continue + fields = fields_of(metric) + items[metric_id] = {"name": str(metric.get("name") or ""), "fields": fields, + "field_count": len(fields), + "expected_fields": sorted(fields), "missing_fields": []} + metric_ids.append(metric_id) + total += len(fields) + # 首次接受导入收的是**整张卡**的指标,逐格都有值:覆盖是完整的。之后按字段推进(advance)会把它降成 partial。 + return {"kind": KIND, "version": VERSION, "card_id": str(card_id or ""), + "workflow_id": str(workflow_id or ""), "accepted_revision": int(accepted_revision), + "accepted_at": str(accepted_at or ""), "accepted_by": accepted_by, + "source_snapshot": dict(source_snapshot) if isinstance(source_snapshot, Mapping) else None, + "metric_ids": metric_ids, "metrics": items, "field_count": total, + "coverage": {"status": "complete", + "metrics": {mid: {"covered": int(item["field_count"]), + "expected": int(item["field_count"]), "missing": []} + for mid, item in items.items()}, + "uncovered_metric_ids": []}} + + +async def put_metrics(*, metrics: Iterable[Any], card_id: str, workflow_id: str, accepted_revision: int, + source_snapshot: Mapping[str, Any] | None = None, draft_id: str = "", + accepted_at: str = "", accepted_by: str | None = None) -> dict[str, Any] | None: + """把这一份被接受的字段值存成不可变工件,返回 payload 里要记的引用;落库失败返回 None。 + + 落库失败不让草稿失败:草稿照出,但没有引用就等于 baseline_unknown(照实说「当时的导入值还原不出来」), + 不假装有基线。引用里的 content_hash 就是工件 id(内容寻址,同一份材料只存一次)。 + """ + from app.db.base import utcnow + + made = document(metrics=metrics, card_id=card_id, workflow_id=workflow_id, + accepted_revision=accepted_revision, source_snapshot=source_snapshot, + accepted_at=accepted_at or utcnow().isoformat(), accepted_by=accepted_by) + if not made["metric_ids"]: + return None + try: + from app.core.artifact_store import put_json + + artifact_id = await put_json(made, kind=KIND, node_id=draft_id or None, + meta={"draft_id": draft_id, "card_id": str(card_id or ""), + "accepted_revision": int(accepted_revision), + "field_baseline_version": VERSION}) + except Exception: # noqa: BLE001 - 基线落库失败照实记「没有基线」,不把整份草稿判死 + logger.exception("字段基线落库失败(草稿 %s)", draft_id) + return None + return {"artifact_id": artifact_id, "kind": KIND, "version": VERSION, + "content_hash": artifact_id, "card_id": made["card_id"], + "workflow_id": made["workflow_id"], "accepted_revision": int(accepted_revision), + "accepted_at": made["accepted_at"], "metric_ids": list(made["metric_ids"]), + "field_count": made["field_count"], + "source_snapshot_artifact_id": str((source_snapshot or {}).get("artifact_id") or "") + if isinstance(source_snapshot, Mapping) else ""} + + +async def advance(*, ref: Any, updates: Mapping[str, Mapping[str, Any]], card_id: str = "", + workflow_id: str = "", accepted_revision: int, draft_id: str = "", + source_snapshot: Mapping[str, Any] | None = None, accepted_at: str = "", + accepted_by: str | None = None, card_metric_ids: Iterable[str] | None = None, + ) -> dict[str, Any] | None: + """**按字段**推进 B(K11):把这次被接受的字段值并进当前基线,存成一件新的不可变工件,交回新引用。 + + B 是「上一次被接受的导入值」:只有**接受**的字段才往前走,没提到的(含未接受的冲突)原样留着。传入的 updates 是 + {metric_id: {"name": …, "fields": {field_path: 值}, "expected_fields": [这条指标在卡上声明的字段路径]}}—— + 值原样深拷贝、逐格另算值哈希(和 fields_of 同一套),所以重导入仍有东西可比。 + + **读不回来的时候从空开始。** 老草稿没有引用、工件被删或被改,`read` 都还原不出 B;这时不能拿当前内容倒填历史, + 就建一份**只含这次明确接受的那几格**的新基线:其余格仍旧没有基线,下次重导入会按「新增候选 / 需要人工对齐」处理。 + 这正是「baseline_unknown 必须人工对齐」的落点:先有人的接受,才有这一格的历史。 + + **覆盖照实记(coverage)。** 一次按字段的接受多半只覆盖卡上的一部分:`expected_fields` 说这条指标在卡上总共 + 声明了哪些格、`card_metric_ids` 说卡上总共有哪几条指标。没覆盖到的格和整条没有基线的指标都记下来, + `coverage.status` 因此是 partial——**不能把整张卡伪装成完整 known**。首次接受导入(document/put_metrics) + 收的是整张卡,那才是 complete。 + + **同一份材料只存一份。** 工件按内容寻址:同样的接受重放两次得到同一个工件 id,B 不会因为重放而多出一份。 + 落库失败返回 None:调用方照实说基线没推进,不假装有(调用方据此让这次接受整体不落库)。 + """ + import copy + + from app.core.artifact_store import canonical_json, content_hash, put_json + from app.db.base import utcnow + + try: + made = read(ref) if ref else None + except Exception: # noqa: BLE001 - 工件被改过(哈希不符)也算读不出来:从这次接受的字段重建 + made = None + base = copy.deepcopy(dict(made)) if isinstance(made, Mapping) and made.get("kind") == KIND else None + metrics: dict[str, Any] = dict(base.get("metrics")) if base and isinstance(base.get("metrics"), dict) else {} + order: list[str] = [str(mid) for mid in (base or {}).get("metric_ids") or []] if base else [] + for raw_id, payload in (updates or {}).items(): + metric_id = str(raw_id or "").strip() + if not metric_id: + continue + entry = metrics.get(metric_id) + entry = dict(entry) if isinstance(entry, Mapping) else {"name": "", "fields": {}} + fields = dict(entry.get("fields")) if isinstance(entry.get("fields"), dict) else {} + name = str((payload or {}).get("name") or entry.get("name") or "") + if name: + entry["name"] = name + for path, value in ((payload or {}).get("fields") or {}).items(): + kept = copy.deepcopy(value) + fields[str(path)] = {"value": kept, "hash": content_hash(canonical_json(kept))} + # 这一格有没有基线、这条指标在卡上还差哪些格:按字段推进之后 coverage 会降成 partial + expected = payload.get("expected_fields") if isinstance(payload, Mapping) else None + expected_set = {str(p) for p in expected} if isinstance(expected, (list, tuple)) else set(fields) + expected_set |= set(fields) + entry["fields"], entry["field_count"] = fields, len(fields) + entry["expected_fields"] = sorted(expected_set) + entry["missing_fields"] = sorted(expected_set - set(fields)) + metrics[metric_id] = entry + if metric_id not in order: + order.append(metric_id) + total = sum(int((item or {}).get("field_count") or 0) for item in metrics.values()) + uncovered = [str(mid) for mid in (card_metric_ids or []) if str(mid) not in metrics] + coverage_metrics = { + mid: {"covered": len((item or {}).get("fields") or {}), + "expected": len((item or {}).get("expected_fields") or (item or {}).get("fields") or {}), + "missing": list((item or {}).get("missing_fields") or [])} + for mid, item in metrics.items() + } + partial = bool(uncovered) or any(entry["missing"] for entry in coverage_metrics.values()) + document = { + "kind": KIND, "version": VERSION, + "card_id": str(card_id or (base or {}).get("card_id") or ""), + "workflow_id": str(workflow_id or (base or {}).get("workflow_id") or ""), + "accepted_revision": int(accepted_revision), "accepted_at": str(accepted_at or utcnow().isoformat()), + "accepted_by": accepted_by, + "source_snapshot": dict(source_snapshot) if isinstance(source_snapshot, Mapping) + else (base or {}).get("source_snapshot"), + "metric_ids": order, "metrics": metrics, "field_count": total, + "coverage": {"status": "partial" if partial else "complete", "metrics": coverage_metrics, + "uncovered_metric_ids": uncovered}, + } + try: + artifact_id = await put_json(document, kind=KIND, node_id=draft_id or None, + meta={"draft_id": draft_id, "card_id": document["card_id"], + "accepted_revision": int(accepted_revision), + "field_baseline_version": VERSION, "advanced": True, + "coverage": document["coverage"]["status"]}) + except Exception: # noqa: BLE001 - 推进失败照实说没有推进,调用方让整次接受不落库 + logger.exception("字段基线推进失败(草稿 %s)", draft_id) + return None + return {"artifact_id": artifact_id, "kind": KIND, "version": VERSION, + "content_hash": artifact_id, "card_id": document["card_id"], + "workflow_id": document["workflow_id"], "accepted_revision": int(accepted_revision), + "accepted_at": document["accepted_at"], "metric_ids": list(order), "field_count": total, + "coverage": document["coverage"], + "source_snapshot_artifact_id": str((source_snapshot or {}).get("artifact_id") or "") + if isinstance(source_snapshot, Mapping) else ""} + + +def coverage_of(doc: Any) -> dict[str, Any]: + """这份 B 覆盖到哪一步:complete(卡上每条指标的每一格都有基线)/ partial(还有没基线的格或整条指标)。 + + 老工件没有 coverage 这一段(加它之前 put_metrics 收的是整张卡)时按 complete 处理,不 backfill、不猜。 + 返回 {status, metrics: {mid: {covered, expected, missing}}, uncovered_metric_ids}。 + """ + if not isinstance(doc, Mapping): + return {"status": "unknown", "metrics": {}, "uncovered_metric_ids": []} + kept = doc.get("coverage") + if isinstance(kept, Mapping) and kept.get("status"): + return {"status": str(kept["status"]), "metrics": dict(kept.get("metrics") or {}), + "uncovered_metric_ids": [str(mid) for mid in kept.get("uncovered_metric_ids") or []]} + metrics = doc.get("metrics") if isinstance(doc.get("metrics"), dict) else {} + out: dict[str, Any] = {} + for mid, entry in metrics.items(): + count = len((entry or {}).get("fields") or {}) + out[str(mid)] = {"covered": count, "expected": count, "missing": []} + return {"status": "complete", "metrics": out, "uncovered_metric_ids": []} + + +def read(ref: Any) -> dict[str, Any] | None: + """按引用读回那份基线工件(load 会复验哈希)。引用不对、工件不在或被改过时返回 None / 抛 ValueError 由调用方定。""" + from app.core.artifact_store import load + + artifact_id = ref.get("artifact_id") if isinstance(ref, Mapping) else None + if not isinstance(artifact_id, str) or not artifact_id: + return None + made = load(artifact_id) + if not isinstance(made, dict) or made.get("kind") != KIND: + return None + return made + + +def values(ref: Any, metric_id: str | None = None) -> dict[str, Any]: + """按引用读出字段值:不给 metric_id 时是 {metric_id: {field_path: 值}},给了就是那一条的 {field_path: 值}。 + + 读不回来(没有引用、工件不在了)返回空 dict——「读不到 B」由 status_of 说,不在这里编一份出来。 + """ + made = read(ref) + if made is None: + return {} + items = made.get("metrics") if isinstance(made.get("metrics"), dict) else {} + if metric_id is not None: + entry = items.get(str(metric_id)) or {} + fields = entry.get("fields") if isinstance(entry, dict) else {} + return {str(path): (cell or {}).get("value") + for path, cell in (fields or {}).items() if isinstance(cell, Mapping)} + return {str(mid): {str(path): (cell or {}).get("value") + for path, cell in ((entry or {}).get("fields") or {}).items() + if isinstance(cell, Mapping)} + for mid, entry in items.items()} + + +def history(payload: Any) -> list[dict[str, Any]]: + """这份草稿接受过的导入基线,按先后(每次接受追加一条;当前 B 是最后一条)。""" + if not isinstance(payload, Mapping): + return [] + kept = payload.get(HISTORY_KEY) + return [dict(item) for item in kept if isinstance(item, Mapping)] if isinstance(kept, list) else [] + + +def ref_of(payload: Any) -> dict[str, Any] | None: + """这份草稿当前的字段基线引用;没有就是 None。""" + ref = payload.get(REF_KEY) if isinstance(payload, Mapping) else None + return dict(ref) if isinstance(ref, Mapping) and ref.get("artifact_id") else None + + +def status_of(payload: Any) -> dict[str, Any]: + """这份草稿的字段基线是什么状态:known(有**读得回来**的接受导入值)/ baseline_unknown(没有或读不回来)。 + + **有引用不等于有基线,也不等于验证通过。** 这里会把工件真的读一遍(load 会复验哈希):工件不在、内容被改过、 + 或工件的种类不对,都照实说 baseline_unknown 并把 readable 标成 false——「工件坏了」不能报成 known, + 也不能在读草稿时抛出去把页面弄崩。老草稿(保存基线之前起草的)同样 baseline_unknown:不能拿它现在的内容 + 冒充 B,也不能因为「读不到」就当通过。 + + **known 不等于完整。** 按字段推进(advance)出来的基线常常只覆盖卡上的一部分:`coverage` 逐条指标说清了 + 覆盖了几格、还缺哪些格,`coverage.status` 是 complete / partial(老工件没有这一段按 complete 处理)。 + 界面上「这条草稿有没有基线」看 status,「这张卡是不是整张都有基线」看 coverage——两件事,不能混。 + """ + ref = ref_of(payload) + stored = payload.get(REF_KEY) if isinstance(payload, Mapping) else None + if ref is None and isinstance(stored, Mapping) and not stored.get("artifact_id") and stored.get("status"): + # 已经是一份状态(落库失败时写下的那种):原样交回,不重算、不补字段 + return dict(stored) + if ref is None: + return {"status": "baseline_unknown", "readable": False, + "coverage": {"status": "unknown", "metrics": {}, "uncovered_metric_ids": []}, + "reason": "这份草稿没有字段基线(保存基线之前起草的,或这次落库失败):当时被接受的导入值无法还原," + "不能拿当前内容当作 B"} + try: + made = read(ref) + except Exception as e: # noqa: BLE001 - 工件被改过(哈希不符)也算读不出来,照实说,不让读草稿失败 + logger.warning("字段基线工件读不出来(%s):%s", ref.get("artifact_id"), e) + made = None + if not isinstance(made, Mapping): + return {"status": "baseline_unknown", "readable": False, "artifact_id": ref["artifact_id"], + "version": ref.get("version") or VERSION, "accepted_revision": ref.get("accepted_revision"), + "coverage": {"status": "unknown", "metrics": {}, "uncovered_metric_ids": []}, + "reason": "字段基线工件读不回来(不在、内容与哈希不符,或不是字段基线工件):" + "当时被接受的导入值无法还原,不能拿当前内容当作 B"} + return {"status": "known", "readable": True, "artifact_id": ref["artifact_id"], + "version": ref.get("version") or VERSION, + "content_hash": str(ref.get("content_hash") or ref["artifact_id"]), + "card_id": str(ref.get("card_id") or ""), "workflow_id": str(ref.get("workflow_id") or ""), + "accepted_revision": ref.get("accepted_revision"), "accepted_at": ref.get("accepted_at") or "", + "metric_ids": [str(mid) for mid in ref.get("metric_ids") or []], + "field_count": ref.get("field_count") or 0, "coverage": coverage_of(made), + "source_snapshot_artifact_id": str(ref.get("source_snapshot_artifact_id") or "")} + + +__all__ = ["CITATIONS_FIELD", "HISTORY_KEY", "KIND", "REF_KEY", "VERSION", "accepted_card", "advance", + "coverage_of", "document", "field_paths", "fields_of", "history", "put_metrics", "read", "ref_of", + "status_of", "value_at", "values"] diff --git a/backend/app/ledger/issue.py b/backend/app/ledger/issue.py index c66ba79c..01c2843c 100644 --- a/backend/app/ledger/issue.py +++ b/backend/app/ledger/issue.py @@ -16,7 +16,9 @@ - 那一版已发布、未退役; - 图里没有人工节点、不会写外部系统(apps/backfill.graph_side_effect,和按新口径补算同一个判断):替人重跑一次的正式 运行不该替人去审批、往外部系统写; -- 补了缺省值之后表单校验通过(缺入口字段的照实说缺哪个); +- 补了缺省值之后表单校验通过(缺入口字段的照实说缺哪个);这次的输入按参数完整性(ledger/params,各入口同一套)过一遍 + 取数模板:缺参数(含绑定出来的是空串——空串不是值)、未声明参数、值承载不了、认不出参数写在哪(混进了运行时变量、 + 参数写在表名或列名里)都不代填出具,明确不发那一条 SQL; - 权限(拍板 L5):搭建者及以上(关登录时同)都可以;使用者只能按他有权使用的应用固定着的这一版出具(复用应用授权, apps/access),别的写「请搭建者出具」;都要读得到这次运行; - 当天没超上限(设置 ledger.issue_daily_limit,自动的、一键的合计)。 @@ -113,6 +115,8 @@ class Plan: granted_by_app: str | None = None #: 已经发起过的同一次(没失败的) existing: str | None = None + #: K07:这一版的发布依据(哪一版、哪份清单、什么身份);读不出来时是 None + publication: dict[str, Any] | None = None @property def available(self) -> bool: @@ -131,6 +135,9 @@ class Plan: "caliber": self.caliber, "workflow_name": self.workflow_name, "how": self.how, "level": self.level, "level_text": LEVEL_TEXT.get(str(self.level or ""), ""), "available": self.available, "auto": self.available and self.auto_reason is None} + if self.publication is not None: + # K07:这一次出具会固定哪一份发布依据(清单、哪一版、什么身份) + out["publication"] = dict(self.publication) if self.reason: out["reason"] = self.reason elif self.auto_reason: @@ -191,16 +198,11 @@ async def _starter(session: Any, run: Run) -> Any: async def _granting_app(session: Any, principal: Any, workflow_id: str, version: int) -> str | None: - """使用者能按这一版出具,靠的是哪个应用的授权:固定着这一版、他至少能使用的应用(apps/access)。没有为 None。""" - from app.apps.access import app_role, at_least - from app.apps.versions import pinning_apps - from app.db.models_apps import App + """使用者能按这一版出具,靠的是哪个应用的授权:固定着这一版、他至少能使用的应用(apps/access 的口径资产授权,和 + 组合式问数「我能用哪些口径」同一份判定)。没有为 None。""" + from app.apps.access import caliber_granting_app - for item in await pinning_apps(session, workflow_id, version): - app = await session.get(App, item["app_id"]) - if app is not None and at_least(await app_role(session, principal, app), "use"): - return app.id - return None + return await caliber_granting_app(session, principal, workflow_id, version) async def plan_issue(session: Any, run: Run | None, content: dict[str, Any] | None, workflow_id: str, version: int, *, @@ -251,7 +253,8 @@ async def plan_issue(session: Any, run: Run | None, content: dict[str, Any] | No async def check_target(session: Any, plan: Plan, workflow: Any, *, principal: Any, source_run: str) -> Plan | None: """按口径出具的那一版能不能发起(plan_issue 和召回待办的「按新版重新出具」共用,ledger/recall.reissue):那一版已发布、 - 未退役;图里没有人工节点、不会写外部系统;入口字段的缺省值加上 plan.binding 过表单校验、能渲染进取数模板;使用者只能按 + 未退役;图里没有人工节点、不会写外部系统;入口字段的缺省值加上 plan.binding 过表单校验、再按参数完整性过一遍取数模板 + (ledger/params:缺参数、未声明参数、承载不了的值、认不出参数写在哪的模板都拒);使用者只能按 他有权使用的应用固定着的这一版(拍板 L5);同一个来源(source_run)、同一版、同一组参数发起过的交回那一次;当天没超 上限。填好 plan 的 level、expect_hash、inputs、granted_by_app、existing;不能出具的写进 plan.refuse,交回 None。""" from app.api.settings import ledger_settings @@ -277,6 +280,18 @@ async def check_target(session: Any, plan: Plan, workflow: Any, *, principal: An return None plan.level = row.level or plan.level plan.expect_hash = row.graph_hash + # 发布依据(K07):按口径出具也是正式身份,和正式运行同一套判定——已接管到工作流上、且这一版走过新发布入口的 + # 资产,必须有一份覆盖这一版定义/绑定/取数语义、matched、认证确认盖住全部指标的发布依据。**这里没有另一条给 + # 正式身份的路**:真发起的还是 engine/launch.launch_run,那道门禁照样过一遍。 + from app.apps import publications as caliber_publications + + judged = await caliber_publications.judge(session, workflow, version=int(version), + purpose=caliber_publications.PURPOSE_ISSUE, snapshot=row) + if judged is not None: + plan.publication = judged.as_dict() + if (refusal := judged.refusal) is not None: + plan.refuse(f"这一版的发布依据还不够,不能按口径出具:{refusal[1]}", 409, refusal[0]) + return None if reason := await graph_side_effect(session, row.graph, level=row.level): plan.refuse(SIDE_EFFECT.format(name=workflow.name, version=version, reason=reason)) return None @@ -287,13 +302,18 @@ async def check_target(session: Any, plan: Plan, workflow: Any, *, principal: An if errors := validate_form(input_schema(fields), values): plan.refuse(INPUTS.format(problems=";".join(e["message"] for e in errors))) return None - # 参数运行时要渲染进口径的 SQL 模板:写在引号里的不能带引号、裸写的只能是数(ledger/compose 同一个判断) - from app.ledger.compose import slot_contexts, value_problem + # 这次的输入要渲染进口径的 SQL 模板,按参数完整性过一遍(ledger/params,trial、组合式问数、派生各入口同一套): + # 模板引用了入口没声明的字段、这次没有值(含绑定出来的是空串——空串不是值,是省略)、值承载不了(引号里带引号、 + # 裸写的不是数)、认不出参数写在哪(入口字段和运行时变量混在一句里、参数写在表名或列名里)都不代填出具。最后那一种 + # 在画布上写得出,但这一版固定下来渲染不出确定的语句,和 trial、组合式问数是同一个判断(口径那张卡自己的取数模板 + # 这样写,在派生那一步就已经拒了,derive.load_pinned)。以前只查承载方式那一层、还把认不出写法的整条放过:缺参数会 + # 按空串渲染,掺杂运行时变量的模板会照发——发起一次「少了条件」或语句已变的正式运行。 + from app.ledger import params - contexts = slot_contexts([n for n in (row.graph or {}).get("nodes") or [] if n.get("type") == "tool"], - strict=False) - if problem := next((p for k, v in values.items() if (p := value_problem(k, v, contexts.get(k, set())))), None): - plan.refuse(f"{problem},不代填出具") + fetches = [n for n in (row.graph or {}).get("nodes") or [] if n.get("type") == "tool"] + if problems := params.check_nodes(fetches, fields=fields, values=values, + where=f"口径「{workflow.name}」v{version} 的入口"): + plan.refuse(f"{params.describe(problems)},不代填出具") return None if principal.mode != "off" and not principal.at_least("builder"): plan.granted_by_app = await _granting_app(session, principal, workflow_id, int(version)) @@ -372,7 +392,9 @@ async def issue(run_id: str, workflow_id: str, version: int, *, principal: Any, origin = {"source_run": run_id, **await _conversation_of(session, run), "caliber": plan.caliber, "how": plan.how, "binding_hash": input_key(plan.binding), "match": plan.match_artifact, - "auto": auto, **({"granted_by_app": plan.granted_by_app} if plan.granted_by_app else {})} + "auto": auto, **({"granted_by_app": plan.granted_by_app} if plan.granted_by_app else {}), + # K07:按哪一份发布依据出具(清单、版本、身份)——运行来源里保留,回看对得上 + **({"publication": plan.publication} if plan.publication else {})} actor = run.started_by if auto else principal.username # 先占一份今天的额度(库里带条件的加一,几个进程同时出具也正好到上限为止),发起不成退回 from app.api.settings import ledger_settings diff --git a/backend/app/ledger/match.py b/backend/app/ledger/match.py index b2e8086f..25b14054 100644 --- a/backend/app/ledger/match.py +++ b/backend/app/ledger/match.py @@ -5,9 +5,9 @@ 放在封存之前,外部的口径表就混进了运行自身的封存事实。正式运行不比 SQL——它本身就是某一版的承诺,账本按 Run.workflow_id / version 记。系统派生的运行(评测、对账、召回)不比:它们是服务端为了量、为了比替人跑的(engine/origin.SYSTEM_ORIGINS)。 -**和谁比。** 每个工作流最新的已发布、未退役版本(apps/versions.latest_published,和 look 的 caliber、蓝图复用口径同一种说法, -拍板 L4:受管、已发布都算,标签写明级别)里查库的调用工具节点。先按同一个数据源、SQL 里的表有交集预筛,每条查询最多比 -MAX_CANDIDATES 份(按工作流、版本、节点排好的先后)。 +**和谁比。** 每个工作流**推荐发布版**里的口径取数(K07:Workflow.published_version,和 look 的 caliber、蓝图复用口径 +同一种说法;最高已发布版只在升级发现里用),拍板 L4:受管、已发布都算,标签写明级别)里查库的调用工具节点。先按同一个 +数据源、SQL 里的表有交集预筛,每条查询最多比 MAX_CANDIDATES 份(按工作流、版本、节点排好的先后)。 **怎么比。** data/sql_semantics.match_template:先绑定参数(只是启发),再按绑定渲染口径的取数 SQL 交 explain_sql_diff 证明。 @@ -248,19 +248,26 @@ def caliber_of(workflow_id: str, row: Any) -> Caliber | None: async def load_calibers(session: Any) -> list[Caliber]: - """每个工作流最新的已发布、未退役版本里的口径取数(apps/versions.is_published,同 latest_published 的说法)。先只读版本号 - 和级别挑出每个工作流的那一版,再读这几版的图。""" + """每个工作流**推荐发布版**里的口径取数(K07:默认调用读推荐版 Workflow.published_version;最高已发布版只在 + 升级发现里用)。先只读版本号和级别挑出每个工作流的那一版,再读这几版的图。""" from app.apps.versions import is_published rows = (await session.execute( select(WorkflowVersion.id, WorkflowVersion.workflow_id, WorkflowVersion.version, WorkflowVersion.level, WorkflowVersion.retired_at, Workflow.published_version) .join(Workflow, Workflow.id == WorkflowVersion.workflow_id))).all() - latest: dict[str, tuple[int, str]] = {} + published: dict[str, list[tuple[int, str]]] = {} + recommended: dict[str, int | None] = {} for vid, wid, version, level, retired, current in rows: probe = _VersionProbe(version, level, retired) - if is_published(probe, current=current) and version > latest.get(wid, (0, ""))[0]: - latest[wid] = (version, vid) + recommended[wid] = current + if is_published(probe, current=current): + published.setdefault(wid, []).append((version, vid)) + latest: dict[str, tuple[int, str]] = {} + for wid, found in published.items(): + current = recommended.get(wid) + pick = next((item for item in found if item[0] == current), None) + latest[wid] = pick or max(found) if not latest: return [] ids = [vid for _, vid in latest.values()] diff --git a/backend/app/ledger/nlchange.py b/backend/app/ledger/nlchange.py new file mode 100644 index 00000000..c6f1b0d3 --- /dev/null +++ b/backend/app/ledger/nlchange.py @@ -0,0 +1,1015 @@ +"""受限的自然语言修改与固定请求路由(K12):自然语言只产出一份**提案**,写仍然走 K03 那条路。 + +这一层解决两件事,都刻意做得很小、很受限: + +**一、自然语言改口径只产出「K03 同一份 ChangeSet 提案」。** 一次提议只说三样东西——一批 K03 的字段操作 +(op / metric_id / path / value,白名单和写法见 app/ledger/changes.py)、这次会影响什么(影响指标、失效说明、绑定状态, +由 `changes.summary` 在同一条路上算出来)、以及**必须先问清的澄清项**。没有第二条写路径:提案不落库、不新增版本, +真要用它,客户端把 operations 交给现有的 `PATCH /api/ledger/drafts/{id}`(expected_revision / request_id 幂等 / +CAS / 绑定同步 / 校验一条不少),或者调这里的薄适配入口(同样落回 `PATCH`,且要带客户端确认)。**失败不擅自改口径**: +说不清就只给澄清项,一条操作都不产出。 + +识别只认**已声明的能力**(`bindings.editable_fields()`:统计时间口径、退款处理等业务字段,每个字段允许的取值和说法)。 +不写通用聊天 DSL,也不解析任意字段:一句话里提到某个业务字段、又指定了它某个允许的取值,才落成操作;提到字段却说不清 +取哪个值(比如「排除退款」——词汇表里只有「排除全额退款」和「全部计入」,全额/部分没分开),就产出澄清项,不替它猜。 +没提到任何已声明能力,同样只给澄清项,不静默当成「不用改」。 + +判「有没有在谈这个字段」按**规则/条件**算,不按名词算:光有名词(`_FIELD_NOUNS`)不算——指标名里带「退款」 +(「退款率」)不等于在谈退款规则,`propose` 还会先把卡上指标的名字和同义词挖掉再识别。**否定不反向**:登记过的否定 +(`_NEGATED_MEANS`,「不排除全额退款」= 全部计入、也就是「不要排除/不排除/无需排除全额退款」都落成 `include_all`) +翻成它真正的意思;没登记的否定(「不按支付时间」)既不认这个值、也不认它的反面,只报说不清。 + +**模型只能提建议。** `from_model` 收的是一份模型产出的 JSON:里面的 operations 照 `changes` 的白名单和值域逐条校验, +**actor / review / verified / approved 这类「自报批准」的键一律丢掉**(记进 ignored_claims),影响摘要和失效结论一律 +由平台按图现算——模型说「已批准」「已验证」「不会失效」都不算数。 + +**二、Ask Data 的固定请求路由。** 已经明确 workflow + card + metric_ids + inputs 的确定请求直接进 QueryCore +(app/ledger/querycore.py),路由只把版本固定一次(点名就固定到它、不点名读推荐版并当场固定),交给 `execute` 时带上 +那一版,QueryCore 不再另挑一次;执行路径内部 LLM 仍为 0。没有匹配到口径(工作流/卡指不到、这一版没有这张卡)就**明确 +进探索**,含糊的业务条件(说不清取哪个值)先澄清;请求里的业务条件和匹配到的那一版声明的算法对不上时,**不静默换计算 +规则**,照实说要先受限修改口径或点名匹配的那一版。外层模型可以提建议(`from_model`),但路由本身不调模型。 + +**三、普通问数的保守默认路由。** `auto_route` 给「没有显式固定请求」的普通问数一次**高置信才命中**的机会:按推荐发布 +版的指标 name / 唯一 synonym 规范化精确匹配**唯一**一个指标、这句话没有含糊业务条件、这次入口取值拿得全且类型可证, +才交回一条固定请求(调用方据此执行);**任何一处不确定都交回 None**,调用方原样走旧的 Agent 路径,不向用户多说什么、也 +不替它挑一份口径。不模糊相似、不按整卡、不问模型;跨卡同名或一句指到不止一个指标都不自动。 + +匹配**仍按全部发布口径**看(`_auto_cards`),所以「没匹配到」和「命中了但这个人没有使用权」区分得开:调用方把 +`allowed`(`(workflow_id, version)` 的集合,来自资产授权,app/apps/access.usable_calibers)传进来,唯一命中却不在其中 +时交回**终止型**的 `ROUTE_REFUSED` / `ROUTE_NOT_PERMITTED`——这不是「未匹配」,调用方据此照实说没有授权,**不回退旧的 +Agent 路径**:那条路会去翻底表,等于拿着一句高置信的问法绕开这份口径的授权。`allowed` 是 None 表示调用方已放行 +(搭建者及以上:它们本来就能直接按口径执行),不按资产授权收窄——那几个角色不进资产授权函数。 +""" +from __future__ import annotations + +import re +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field +from datetime import date +from typing import Any + +from app.ledger import bindings, changes +from app.ledger.repository import GraphBackedCaliberRepository + +# 机器码(接口按它们回结构化拒绝;给人看的说法另在 message / question 里) +#: 一句话里提到的业务条件说不清取哪个值:必须先澄清 +PROPOSAL_AMBIGUOUS = "change_proposal_ambiguous" +#: 一句话里没有提到任何已声明的能力 +PROPOSAL_NONE = "change_proposal_no_match" + +#: 澄清项的类别 +KIND_AMBIGUOUS = "ambiguous" # 提到了字段,但取值说不清 +KIND_NO_MATCH = "no_match" # 没提到任何已声明能力 +KIND_MISSING = "missing" # 请求少了确定请求必需的一项(路由用:要算哪几个指标) + +# 固定请求路由的结论与机器码 +ROUTE_EXECUTE = "querycore" # 确定请求:直接进 QueryCore,不重复解析/规划 +ROUTE_CLARIFY = "clarify" # 还缺一项或业务条件说不清:先澄清 +ROUTE_EXPLORE = "explore" # 没有匹配口径 / 业务条件和口径对不上:进探索,不静默换规则 +#: 唯一命中、但这个人对那一版没有使用权:**终止型**——不是「未匹配」,不回退旧的 Agent 路径(那条路会去翻底表) +ROUTE_REFUSED = "refused" +ROUTE_AMBIGUOUS = "route_ambiguous" # 业务条件说不清 +ROUTE_VERSION_INVALID = "route_version_invalid" # 点名的版本号不是正整数:先说清,绝不静默推荐版 +ROUTE_METRICS_REQUIRED = "route_metric_ids_required" +ROUTE_NO_CALIBER = "route_no_matching_caliber" +ROUTE_CONDITION_MISMATCH = "route_condition_mismatch" +ROUTE_READY = "route_execute" +#: 普通问数里自动命中的固定请求(保守默认路由):命中直接执行,未命中交回 None 走旧 Agent 路径 +ROUTE_AUTO = "route_auto_match" +#: 命中了、但不在这次调用方给的授权范围里(见 auto_route 的 allowed) +ROUTE_NOT_PERMITTED = "route_not_permitted" + +#: 「命中但无权」给人的说法:自动路由的拒绝和固定请求那道闸**共用同一句**,不出现工作流 / 卡 / 版本这类内部引用 +NOT_PERMITTED = "这句话指向的那份固定口径没有授权给你使用:请换一种问法,或让搭建者把这份口径授权给你" + +#: 光凭它就说明在谈这个字段(够具体的说法,不依赖名词)。加了新的声明白名单字段(bindings.FIELDS)时在这里登记; +#: 没登记的字段不参与自然语言识别(但仍可经模型建议 from_model 按字段改)。 +_FIELD_OPERATORS: dict[str, tuple[str, ...]] = { + "refund_rule": ("排除", "剔除", "计入", "算入", "算进", "纳入", "包含", "过滤", "扣除", "去掉"), +} + +#: 字段的「名词」:**要和搭配词一起出现**才算在谈这个字段。光有名词不算——指标名里带「退款」(退款率)不等于 +#: 在谈退款规则,不能因此去问退款处理取哪个值。 +_FIELD_NOUNS: dict[str, tuple[str, ...]] = { + "time_role": ("时间", "日期"), + "refund_rule": ("退款", "退货", "退单"), +} + +#: 和名词搭配的词:名词 + 其中任一个出现,才当成在谈这个字段。 +#: 退款这一列刻意不收「按」「口径」这类通用词——「退款率按支付时间口径算」谈的是时间口径,不是退款规则。 +_FIELD_MATCHERS: dict[str, tuple[str, ...]] = { + "time_role": ("按", "统计", "口径", "算"), + "refund_rule": ("规则", "处理", "方式"), +} + +#: 每个已声明取值除词汇表里的 label 之外另认的说法(label 一定认;加新声明取值不改这里也认)。 +#: 这些是**受控词汇表**的另一层说法,不是通用自然语言解析:只认下面这些整词,不猜。 +#: 「不要排除」「不排除」这类**否定说法本身就是一条正向声明**(不排除 = 全部计入),单列在这里; +#: 别的否定(比如「不按支付时间」)不认,绝不当成它的反面。 +_ALIASES: dict[tuple[str, str], tuple[str, ...]] = { + ("time_role", "order_time"): ("按下单时间", "下单时间", "按订单时间", "按创建时间"), + ("time_role", "payment_time"): ("按支付时间", "支付时间", "按付款时间", "付款时间"), + ("refund_rule", "include_all"): ("不排除", "不要排除", "无需排除", "不用排除", "不必排除", + "不排除退款", "不排除退货", "不剔除", "退款全算"), + ("refund_rule", "exclude_full_refund"): ("排除全额退款", "全额退款排除", "剔除全额退款"), +} + +#: 否定词(出现在取值说法之前时构成否定)。「取消」这类也算否定:否定后面的取值不认,也不翻成它的反面。 +_NEG_PREFIXES: tuple[str, ...] = ("不要", "无需", "不用", "不必", "不能", "没有", "取消", "不", "别", "勿") + +#: 否定**某个取值说法**时真正的意思(不排除全额退款 = 全部计入)。只有这里登记了的才把否定翻成对应的值; +#: 别的否定一律不算命中(既不认这个值,也不认它的反面)——「其他否定也不能反向」。 +_NEGATED_MEANS: dict[tuple[str, str], str] = { + ("refund_rule", "exclude_full_refund"): "include_all", +} + + +def _is_negative_form(phrase: str) -> bool: + """这个说法本身是不是一条否定形式的**正向**声明(「不排除」这类):是的话不再按否定处理。""" + return any(phrase.startswith(prefix) for prefix in _NEG_PREFIXES) + + +def _negated(text: str, at: int) -> bool: + """取值说法前面紧挨着一个否定词(最多看 3 个字的窗口)。""" + before = text[max(0, at - 4):at] + return any(before.endswith(prefix) for prefix in _NEG_PREFIXES) + +#: 模型不能自报的键(顶层和每条操作里都清掉):批准、主体、审阅、验证结论、失效结论这类,一律由平台现算。 +_FORBIDDEN_CLAIM_KEYS: frozenset[str] = frozenset({ + "actor", "role", "review", "reviewer", "reviewed", "reviewed_by", "approve", "approved", "approval", + "approver", "verified", "verify", "authorized", "status", "signoff", "signed_off", "applied", "change", + "validation", "summary", "created_by", "performed_by", +}) + + +def declared_capabilities() -> list[dict[str, Any]]: + """已声明的能力(业务字段 + 允许的取值和说法):服务端词汇表原样交回,识别只看它。""" + return bindings.editable_fields() + + +def _phrases_with(capability: Mapping[str, Any], value: str, + aliases: Mapping[tuple[str, str], tuple[str, ...]]) -> tuple[str, ...]: + """一个允许取值的所有说法:词汇表里的 label、机器值本身,加上登记过的同义说法(去空白、去重)。""" + labels = (capability.get("value_labels") or {}).get(value) + raw: list[Any] = [labels, value, *(aliases.get((str(capability.get("field")), str(value)), ()))] + out: list[str] = [] + for phrase in raw: + text = str(phrase or "").strip() + if text and text not in out: + out.append(text) + return tuple(out) + + +def _discussed(capability: Mapping[str, Any], text: str, *, + aliases: Mapping[tuple[str, str], tuple[str, ...]]) -> bool: + """这句话在不在谈这个字段的**规则/条件**:写了字段名、出现它某个允许取值的说法、出现够具体的操作词, + 或者名词 + 搭配词一起出现。**光有名词不算**:指标名里带「退款」(退款率)不等于在谈退款规则。""" + name = str(capability.get("field") or "") + if name and name in text: + return True + if any(phrase and phrase in text for value in capability.get("values") or () + for phrase in _phrases_with(capability, value, aliases)): + return True + if any(operator in text for operator in _FIELD_OPERATORS.get(name, ())): + return True + return (any(noun in text for noun in _FIELD_NOUNS.get(name, ())) + and any(matcher in text for matcher in _FIELD_MATCHERS.get(name, ()))) + + +def _blanked(text: str, ignore: Sequence[str]) -> str: + """把不该参与识别的说法(卡上的指标名/同义词)按原长度挖成空格:指标名里带的「退款」不算在谈退款规则。""" + out = text + for phrase in ignore: + piece = str(phrase or "").strip() + if piece and piece in out: + out = out.replace(piece, " " * len(piece)) + return out + + +@dataclass(frozen=True) +class FieldMatch: + """一句话里认出来的一个业务条件:哪个字段、取了哪个允许的值、原话里是哪个说法。""" + + field: str + value: str + label: str + phrase: str + + def as_dict(self) -> dict[str, Any]: + return {"field": self.field, "value": self.value, "label": self.label, "phrase": self.phrase} + + +@dataclass(frozen=True) +class Clarification: + """一个必须先问清的澄清项:kind 是类别,field 是哪个字段(路由里可能是 metric_ids),options 是候选。 + + 「含糊业务条件必须先澄清」就是靠它:识别到某字段却说不清取哪个值时,把该字段的允许取值原样列出来,不替人猜。""" + + kind: str + field: str | None + question: str + options: tuple[dict[str, str], ...] = () + + def as_dict(self) -> dict[str, Any]: + return {"kind": self.kind, "field": self.field, "question": self.question, + "options": [dict(option) for option in self.options]} + + +@dataclass(frozen=True) +class Proposal: + """一份受限修改提案:K03 的 operations、影响摘要(preview)、澄清项、模型自报的键。 + + ready 为真才谈得上应用(有操作、没有澄清项)。operations 原样可以交给 `PATCH /api/ledger/drafts/{id}`; + preview 就是在同一批操作上跑一次 `changes` 得到的回执(含失效与绑定结论),但**不落库、不新增版本**。""" + + card: str + operations: tuple[dict[str, Any], ...] = () + clarifications: tuple[Clarification, ...] = () + metrics: tuple[str, ...] = () + preview: dict[str, Any] | None = None + ignored_claims: tuple[str, ...] = () + notes: tuple[str, ...] = () + + @property + def ready(self) -> bool: + return bool(self.operations) and not self.clarifications + + def as_dict(self) -> dict[str, Any]: + return {"card": self.card, "ready": self.ready, + "operations": [dict(op) for op in self.operations], + "metrics": list(self.metrics), + "clarifications": [item.as_dict() for item in self.clarifications], + "preview": dict(self.preview) if self.preview is not None else None, + "ignored_claims": list(self.ignored_claims), + "notes": list(self.notes)} + + +# -------------------------------------------------------------------------- +# 自然语言 → 业务条件 +# -------------------------------------------------------------------------- + + +def match_conditions(instruction: str, *, + ignore: Sequence[str] = ()) -> tuple[list[FieldMatch], list[Clarification]]: + """一句话 →(认出来的业务条件, 必须先澄清的项)。只认已声明的能力,不做通用解析。 + + 提到某个字段、又指定了它某个允许取值 → 一条 FieldMatch;提到字段却说不清取值(或者一句话里说了两个冲突的取值)→ + 一条 ambiguous 澄清项。同一个字段只取一条:说清了就是那一条,说不清就只给澄清项、不产出任何操作。 + + `ignore` 是**不该参与识别的说法**(卡上的指标名/同义词):挖掉它们之后再判——指标名里带「退款」不等于在谈退款规则。 + 否定按 `_NEGATED_MEANS` 处理:「不排除全额退款」是「全部计入」,别的否定不认(不翻成反面)。""" + text = _blanked(str(instruction or "").strip(), ignore) + matches: list[FieldMatch] = [] + clarifications: list[Clarification] = [] + if not text.strip(): + return matches, clarifications + for capability in declared_capabilities(): + name = str(capability.get("field") or "") + if not name or not _discussed(capability, text, aliases=_ALIASES): + continue + found, unresolved = _scan_values(capability, text, aliases=_ALIASES) + if len(found) == 1 and not unresolved: + value = found[0] + phrase = _first_phrase(_phrases_with(capability, value, _ALIASES), text) or value + matches.append(FieldMatch(field=name, value=value, label=str(capability.get("label") or name), + phrase=phrase)) + continue + options = tuple({"value": str(value), "label": str((capability.get("value_labels") or {}).get(value) or value)} + for value in capability.get("values") or ()) + label = capability.get("label") or name + if not found: + question = (f"这句话提到「{label}」,但没说清取哪个值:" + f"请指定{'、'.join(option['label'] for option in options) or '具体取值'}") + elif unresolved: + question = f"这句话里「{label}」的否定说不清是什么意思:请直接说是{'、'.join(option['label'] for option in options)}" + else: + question = (f"这句话里「{label}」说了不止一个值" + f"({'、'.join(option['label'] for option in options if option['value'] in found)}):只能取一个") + clarifications.append(Clarification(kind=KIND_AMBIGUOUS, field=name, question=question, options=options)) + return matches, clarifications + + +def _scan_values(capability: Mapping[str, Any], text: str, + *, aliases: Mapping[tuple[str, str], tuple[str, ...]]) -> tuple[list[str], bool]: + """这句话里出现过的允许取值:按**最长的说法先认**并就地消费掉(长说法里的短子串不会被再认一遍)。 + + 交回 (认到的取值, 有没有说不清的否定)。否定**紧挨在取值说法之前**时(「不排除全额退款」):登记过否定含义的翻成对应的 + 值(→ 全部计入);没登记的**不算命中**(既不认这个值,也不认它的反面),只记一句「说不清」。否定形式本身(「不排除」) + 已经是一条正向声明,不再按否定处理。""" + field = str(capability.get("field") or "") + candidates: list[tuple[str, str, bool]] = [] + for value in capability.get("values") or (): + for phrase in _phrases_with(capability, value, aliases): + candidates.append((phrase, str(value), _is_negative_form(phrase))) + consumed = [False] * len(text) + found: list[str] = [] + unresolved = False + for phrase, value, negative_form in sorted(candidates, key=lambda item: -len(item[0])): + start = 0 + while phrase: + at = text.find(phrase, start) + if at < 0: + break + end = at + len(phrase) + start = at + 1 + if any(consumed[at:end]): + continue + for index in range(at, end): + consumed[index] = True + if negative_form: + if value not in found: + found.append(value) + elif _negated(text, at): + mapped = _NEGATED_MEANS.get((field, value)) + if mapped is None: + unresolved = True + elif mapped not in found: + found.append(mapped) + elif value not in found: + found.append(value) + return found, unresolved + + +def _first_phrase(phrases: Sequence[str], text: str) -> str | None: + hits = [phrase for phrase in phrases if phrase and phrase in text] + return max(hits, key=len) if hits else None + + +# -------------------------------------------------------------------------- +# 业务条件 → K03 operations(在原图的深拷贝上试跑) +# -------------------------------------------------------------------------- + + +def _metric_mentions(metrics: Sequence[Mapping[str, Any]]) -> list[str]: + """卡上指标的名字和同义词:识别前先把它们挖掉,指标名里带的词不算在谈业务规则。 + + 进不了已声明取值说法的那些才挖(是某个说法的一部分就留着),免得把「支付」这种指标名挖掉之后 + 「按支付时间」也认不出来了。""" + protected = [phrase for capability in declared_capabilities() + for value in capability.get("values") or () + for phrase in _phrases_with(capability, value, _ALIASES)] + out: list[str] = [] + for metric in metrics: + for name in (metric.get("name"), *(metric.get("synonyms") or [])): + piece = str(name or "").strip() + if piece and piece not in out and not any(piece in phrase for phrase in protected): + out.append(piece) + return out + + +def _named_metrics(metrics: Sequence[Mapping[str, Any]], text: str) -> list[str]: + """一句话里点名了哪几条指标:按 metric_id、名称、同义词认(只在卡上现有的指标里认)。""" + out: list[str] = [] + for metric in metrics: + metric_id = str(metric.get("id") or "") + if not metric_id: + continue + names = [metric_id, str(metric.get("name") or "")] + names += [str(s) for s in metric.get("synonyms") or [] if isinstance(s, str)] + for name in names: + name = name.strip() + if name and name in text and metric_id not in out: + out.append(metric_id) + break + return out + + +def _targets(capability_field: str, metrics: Sequence[Mapping[str, Any]], *, named: Sequence[str], + explicit: Sequence[str]) -> list[str]: + """这条业务条件要改哪几条指标:显式点名 > 声明过这个字段的 > 句子里点名的 > 整卡。 + + 「声明过这个字段的」优先:改的是这张卡现有的统计口径,不动没表态的指标(不擅自把整卡的口径一起换掉)。""" + all_ids = [str(metric.get("id")) for metric in metrics if metric.get("id")] + if explicit: + return [str(m) for m in explicit] + declaring = [str(metric.get("id")) for metric in metrics + if metric.get("id") and bindings.declared(metric).get(capability_field) is not None] + if declaring: + return declaring + if named: + return list(named) + return all_ids + + +def _preview(graph: Mapping[str, Any], card_id: str, operations: Sequence[Mapping[str, Any]]) -> dict[str, Any]: + """在**原图的深拷贝**上把这一批操作跑一遍,交回和真落库同一形状的回执(不落库)。""" + change = changes.apply_operations(graph, card_id=str(card_id), operations=list(operations)) + made = changes.summary(change, applied=bool(change.applied), revision=None) + return {**made, "preview": True, "persisted": False} + + +def preview(graph: Mapping[str, Any], card_id: str, operations: Sequence[Mapping[str, Any]]) -> dict[str, Any]: + """一次 K03 字段变更的预览(不落库):同一批操作交给真落库那条路会得到同一份回执。""" + return _preview(graph, card_id, operations) + + +def propose(graph: Mapping[str, Any], card_id: str, instruction: str, *, + metrics: Sequence[str] | None = None) -> Proposal: + """自然语言 → 受限修改提案。**只产出提案**:operations + 影响摘要 + 澄清项,不落库、不新增版本。 + + 识别只认已声明的能力;说不清(含糊)或没提到任何能力时只给澄清项,一条操作都不产出。认出来的条件按 + `_targets` 落到具体的 metric_id 上,然后再在原图的深拷贝上跑一遍 `changes`,所以回执里的失效与绑定结论和真落库 + 时是同一份。""" + text = str(instruction or "").strip() + repo = GraphBackedCaliberRepository(graph, card_id=str(card_id)) + card_metrics = repo.metrics() + # 指标名/同义词先挖掉再识别:指标名里带「退款」(退款率)不等于在谈退款规则 + matches, clarifications = match_conditions(text, ignore=_metric_mentions(card_metrics)) + if clarifications: + return Proposal(card=str(card_id), clarifications=tuple(clarifications), + notes=("识别到含糊的业务条件:先澄清,一条操作也不产出(不替人猜取值)",)) + if not matches: + return Proposal(card=str(card_id), clarifications=(Clarification( + kind=KIND_NO_MATCH, field=None, + question="这句话里没有能按字段改的已声明能力:要改统计时间口径、退款处理这类业务字段,请指明字段和取值", + options=tuple({"value": str(item.get("field")), "label": str(item.get("label") or item.get("field"))} + for item in declared_capabilities())),), + notes=("没有匹配到已声明能力:只给澄清项,不静默当成「不用改」",)) + + named = _named_metrics(card_metrics, text) + explicit = [str(m) for m in (metrics or []) if str(m or "").strip()] + targets: dict[str, list[str]] = {} + for match in matches: + targets[match.field] = _targets(match.field, card_metrics, named=named, explicit=explicit) + + operations: list[dict[str, Any]] = [] + seen: set[tuple[str, str]] = set() + for match in matches: + for metric_id in targets.get(match.field, []): + key = (metric_id, match.field) + if key in seen: + continue + seen.add(key) + operations.append({"op": "set", "metric_id": metric_id, "path": f"/{match.field}", "value": match.value}) + if not operations: + return Proposal(card=str(card_id), clarifications=(Clarification( + kind=KIND_MISSING, field="metric_ids", + question="这张口径卡上没有可改的指标:先确认要改哪几条指标", + options=tuple({"value": str(metric.get("id")), "label": str(metric.get("name") or metric.get("id"))} + for metric in card_metrics if metric.get("id"))),)) + + made = _preview(graph, card_id, operations) + impacted = tuple(str(m) for m in made.get("metrics") or []) + return Proposal(card=str(card_id), operations=tuple(operations), metrics=impacted, preview=made, + notes=("提案只是建议:默认不自动落版,应用要走现有的 PATCH(expected_revision / request_id / CAS / " + "绑定同步 / 校验)",)) + + +# -------------------------------------------------------------------------- +# 模型建议 → 提案(只提建议,不能自报批准) +# -------------------------------------------------------------------------- + + +def from_model(graph: Mapping[str, Any], card_id: str, payload: Mapping[str, Any] | None, *, + metrics: Sequence[str] | None = None) -> Proposal: + """外层模型的建议 → 提案:operations 逐条过 K03 的白名单和值域,**自报批准/主体/验证的键一律丢掉**。 + + 只采信 operations:影响摘要、失效结论、澄清项都由平台按图现算。模型写的 actor / review / verified / approved / + summary / change / validation 这类键(顶层和每条操作里的都算)进 ignored_claims,绝不当成批准或验证通过。""" + raw = payload if isinstance(payload, Mapping) else {} + ignored = _strip_claims(raw) + operations: list[dict[str, Any]] = [] + for item in raw.get("operations") or []: + if not isinstance(item, Mapping): + continue + cleaned = {key: item[key] for key in ("op", "metric_id", "path", "value") if key in item} + ignored += [key for key in item if key not in cleaned] + operations.append(dict(cleaned)) + if not operations: + return Proposal(card=str(card_id), clarifications=(Clarification( + kind=KIND_NO_MATCH, field=None, question="这次建议里没有可用的字段操作"),), + ignored_claims=tuple(dict.fromkeys(ignored)), + notes=("模型没给出操作:不落任何东西",)) + if metrics: + wanted = {str(m) for m in metrics} + operations = [op for op in operations if str(op.get("metric_id") or "") in wanted] or operations + + made = _preview(graph, card_id, operations) + return Proposal(card=str(card_id), operations=tuple(operations), + metrics=tuple(str(m) for m in made.get("metrics") or []), preview=made, + ignored_claims=tuple(dict.fromkeys(ignored)), + notes=("模型只提建议:operations 过白名单与值域,影响摘要和失效结论由平台现算;" + "自报的批准 / 主体 / 验证结论不采信",)) + + +def _strip_claims(raw: Mapping[str, Any]) -> list[str]: + return [str(key) for key in raw if str(key) in _FORBIDDEN_CLAIM_KEYS] + + +# -------------------------------------------------------------------------- +# Ask Data 固定请求路由 +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class Route: + """一条请求该走哪条路:querycore(直接进固定执行)/ clarify(先澄清)/ explore(进探索)/ refused(命中但没授权)。 + + request 是归一化后的固定请求(mode 为 querycore 时交给执行那条路);clarifications 是澄清项。refused 是**终止型**: + 调用方照实说没有授权,不回退旧的 Agent 路径。""" + + mode: str + code: str + reason: str + request: dict[str, Any] = field(default_factory=dict) + clarifications: tuple[Clarification, ...] = () + + def as_dict(self) -> dict[str, Any]: + return {"mode": self.mode, "code": self.code, "reason": self.reason, + "request": dict(self.request), + "clarifications": [item.as_dict() for item in self.clarifications]} + + +def _ids(value: Any) -> list[str]: + if isinstance(value, str): + value = [value] + return [str(item) for item in (value or []) if str(item or "").strip()] + + +def _explicit_version(value: Any) -> tuple[int | None, str | None]: + """这条请求点名的版本:(版本号, 为什么不算数)。 + + 十进制数字字符串("2")按**显式版本**处理——和整数 2 一样固定到那一版,不退回推荐版。没写(None / 空串)是 + (None, None),交给默认解析;写了但不是正整数("abc"、"2.5"、0、-1、true、对象……)是 (None, 一句为什么), + 入口据此先澄清/拒绝,**绝不静默按推荐版执行**(那等于悄悄换了一版口径)。""" + if value is None: + return None, None + if isinstance(value, str): + text = value.strip() + if not text: + return None, None + if not text.isdigit(): + return None, f"版本号「{text}」不是一个正整数" + number = int(text) + elif isinstance(value, bool): + return None, "版本号要是正整数" + elif isinstance(value, int): + number = value + elif isinstance(value, float) and value.is_integer(): + number = int(value) + else: + return None, "版本号要是正整数" + if number < 1: + return None, "版本号要是正整数(从 1 起)" + return number, None + + +def _source_card_metrics(graph: Mapping[str, Any], card_id: str) -> list[dict[str, Any]] | None: + """这一版图里的源头口径卡上的指标;不是卡、是转抄卡、或者卡不在图里时 None。""" + for node in graph.get("nodes") or []: + if not isinstance(node, Mapping) or str(node.get("id")) != str(card_id): + continue + if node.get("type") != "metrics": + return None + config = ((node.get("data") or {}).get("config") or {}) if isinstance(node.get("data"), Mapping) else {} + if config.get("caliber_from") not in (None, "", {}): + return None + return [dict(metric) for metric in config.get("metrics") or [] if isinstance(metric, Mapping)] + return None + + +def _condition_problem(matches: Sequence[FieldMatch], card_metrics: Sequence[Mapping[str, Any]]) -> str | None: + """请求里的业务条件 vs 这一版声明的算法:对不上就返回一句为什么,能对上返回 None。""" + for match in matches: + spec = bindings.FIELDS.get(match.field) + label = spec.label if spec else match.field + declared = [bindings.declared(metric).get(match.field) for metric in card_metrics] + declared = [value for value in declared if value is not None] + if not declared: + return (f"这一版口径没有声明「{label}」:请求里的「{match.phrase}」说的是另一套算法," + "不静默按这一版算——请先受限修改口径把它声明上,或点名声明了它的那一版") + if any(value != match.value for value in declared): + return (f"请求里的「{match.phrase}」和这一版声明的「{label}」对不上:不静默换计算规则——" + "请先受限修改口径,或点名匹配的那一版") + return None + + +async def _locate(session: Any, *, workflow_ref: str, card_id: str, version: int | None, + purpose: str) -> tuple[dict[str, Any] | None, str | None]: + """定位要执行的那一版这一张卡:交回 (info, 为什么进探索)。 + + info 带 workflow_id / version / metrics(这一版这张源头卡上的指标);指不到、版本没发布、卡不是源头卡时 + info 为 None、另给一句为什么——调用方据此进探索,不静默换一份口径。版本在这里**固定一次**(点名就固定到它、 + 不点名读推荐版并当场固定),交给 execute 时带上那一版,QueryCore 不再另挑一次(不重复解析/规划)。""" + from app.apps import publications + from app.apps.versions import is_published + from app.db.models import Workflow + from app.ledger import querycore + + if not workflow_ref: + return None, "这条请求没有指向一份固定口径:进入探索,不静默挑一份口径执行" + try: + workflow_id = await querycore._workflow_id(session, workflow_ref) + except querycore.QueryCoreRefused: + return None, f"找不到口径「{workflow_ref}」:进入探索,不静默挑一份口径执行" + workflow = await session.get(Workflow, workflow_id) + resolved = await publications.resolve(session, workflow, version=version, purpose=purpose) + if resolved is None: + return None, "这份口径现在没有可执行的已发布版本:进入探索" + if not is_published(resolved.row, current=getattr(workflow, "published_version", None)) \ + or resolved.row.retired_at is not None: + return None, "这一版没有发布或已退役:进入探索,不换一版静默执行" + if not card_id: + return None, "这条请求没有点名口径卡:进入探索,不静默挑一张卡" + card_metrics = _source_card_metrics(resolved.row.graph or {}, card_id) + if card_metrics is None: + return None, f"这一版里没有源头口径卡「{card_id}」:进入探索" + return {"workflow_id": resolved.workflow_id, "version": int(resolved.version), "metrics": card_metrics}, None + + +async def route(session: Any, *, request: Mapping[str, Any] | None, + purpose: str | None = None) -> Route: + """按一条请求决定走哪条路:能确定的直接进 QueryCore,说不清/没匹配的口径进澄清或探索。 + + 判定顺序:版本号先看(不是正整数的先澄清,绝不静默推荐版)→ 定位口径(工作流 + 版本 + 源头口径卡)→ 含糊业务 + 条件先澄清(定位到卡就先把卡上的指标名挖掉再判,指标名里带「退款」不算在谈退款规则)→ 请求里的业务条件和这一版 + 声明的算法对不上就进探索(不静默换计算规则)→ 指标没点名就澄清 → 都明确才交回一条可以交给 + `querycore.execute` 的固定请求。定位不到口径时仍按原话判一次含糊条件(含糊照样先澄清),然后进探索。 + + `version` 是十进制数字字符串("2")时按**显式版本**处理;非法版本先澄清/拒绝,不静默按推荐版执行。 + **不调模型**:外层模型可以用 `from_model` 提建议,路由本身零模型。""" + from app.ledger import querycore + + # 用途由宿主常量定(这里默认交互入口那一档);客户端传不了 purpose + purpose = str(purpose or querycore.DEFAULT_PURPOSE) + req = dict(request or {}) + workflow_ref = str(req.get("workflow_id") or req.get("workflow") or "").strip() + card_id = str(req.get("card_id") or req.get("card") or "").strip() + metric_ids = _ids(req.get("metric_ids")) + inputs = req.get("inputs") if isinstance(req.get("inputs"), Mapping) else {} + instruction = str(req.get("instruction") or "").strip() + + # 0) 版本:字符串数字按显式版本处理;非法版本先澄清,绝不静默推荐版 + wanted_version, version_problem = _explicit_version(req.get("version")) + if version_problem is not None: + return Route(ROUTE_CLARIFY, ROUTE_VERSION_INVALID, version_problem, + clarifications=(Clarification( + kind=KIND_MISSING, field="version", + question="要固定到哪一版?版本号写正整数;不确定就先不写,按推荐版执行"),)) + + # 1) 定位口径(版本固定一次) + located, reason = await _locate(session, workflow_ref=workflow_ref, card_id=card_id, + version=wanted_version, purpose=purpose) + + # 2) 含糊业务条件:定位到卡就按卡上的指标名屏蔽后再判;定位不到就按原话判。含糊一律先澄清、不产出操作 + ignore = _metric_mentions(located["metrics"]) if located else [] + matches, clarifications = match_conditions(instruction, ignore=ignore) if instruction else ([], []) + if clarifications: + return Route(ROUTE_CLARIFY, ROUTE_AMBIGUOUS, + "请求里的业务条件说不清取哪个值:先澄清,不按旧口径静默执行", + clarifications=tuple(clarifications)) + if located is None: + return Route(ROUTE_EXPLORE, ROUTE_NO_CALIBER, reason or "没有匹配到口径:进入探索") + + # 3) 业务条件 vs 这一版声明的算法:对不上就不能静默按这一版算 + if matches and (problem := _condition_problem(matches, located["metrics"])) is not None: + return Route(ROUTE_EXPLORE, ROUTE_CONDITION_MISMATCH, problem) + + # 4) 指标必须点名(空的选择不静默当整卡) + if not metric_ids: + return Route(ROUTE_CLARIFY, ROUTE_METRICS_REQUIRED, + "这条请求没有点名要算哪几个指标:先澄清要算哪几个,不静默当整卡", + clarifications=(Clarification( + kind=KIND_MISSING, field="metric_ids", question="要算哪几个指标?", + options=tuple({"value": str(metric.get("id")), "label": str(metric.get("name") or metric.get("id"))} + for metric in located["metrics"] if metric.get("id"))),)) + + return Route(ROUTE_EXECUTE, ROUTE_READY, + "请求已经明确(口径 + 卡 + 指标 + 取值):直接进 QueryCore,不重复解析/规划", + request={"workflow_id": located["workflow_id"], "card_id": card_id, "metric_ids": metric_ids, + "inputs": dict(inputs), "version": located["version"], "purpose": purpose}) + + +# -------------------------------------------------------------------------- +# 普通问数的保守默认路由:高置信确定的请求直接进 QueryCore,其余一律回旧路径 +# +# 这一层只回答一个问题:「这句话是不是**高置信**地指向一份固定口径的某一个指标,参数也拿得全?」是就交回一条 +# 可以直接交给 querycore.execute 的固定请求;**任何一处不确定都交回 None**,由调用方原样走旧的 Agent 路径(不向用户 +# 多说什么、也不澄清)。 +# +# 判「这句话在问哪个指标」用**拆完之后一字不差**,不用包含、也不用模糊相似:先从原话里去掉明确完整的日期/单月 +# (`_auto_remove_dates`,和参数映射同一批写法)、句子里点到的口径/工作流/卡名(`_auto_remainder` 的提示)、以及两端的 +# 通用疑问/查询/统计措辞(`_auto_trim`),剩下的**业务语义**必须和某个指标的 name / 唯一 synonym 完全相等。 +# 「销售额增长率」拆完是「销售额增长率」,和「销售额」不等 → 不直达(增长率/占比/同比/环比/拆解/趋势/明细/排行这些 +# 分析意图词**刻意不算通用措辞**,见 `_AUTO_ANALYSIS_WORDS`);「2026年10月销售额是多少」「查一下销售额」拆完都是 +# 「销售额」→ 直达。跨卡同名或一句指到不止一个指标也不自动;不按整卡、不问模型。 +# -------------------------------------------------------------------------- + +#: 归一化时去掉的字符(空白与常见标点):只用来对比说法,不改变原话 +_AUTO_PUNCT = re.compile(r"[\s\u3000,,。.、;;::!!??()()【】\[\]「」『』\"'“”‘’《》<>~·\-_/]+") +#: 明确完整的单日:2026-10-01 / 2026年10月1日 +_AUTO_DAY_CN = re.compile(r"(\d{4})\s*年\s*(\d{1,2})\s*月\s*(\d{1,2})\s*[日号]") +_AUTO_DAY_DASH = re.compile(r"(? str: + """对比用的归一化:去空白与常见标点、转小写。只用来比说法,不改原话、不做同义改写。""" + return _AUTO_PUNCT.sub("", str(text or "").lower()) + + +def _auto_metric_terms(metric: Mapping[str, Any]) -> list[str]: + """一个指标参与匹配的说法:name 与 synonyms(只收非空字符串)。""" + out: list[str] = [] + for value in [metric.get("name"), *(metric.get("synonyms") or [])]: + text = str(value or "").strip() + if text and text not in out: + out.append(text) + return out + + +async def _auto_cards(session: Any) -> list[dict[str, Any]]: + """每个工作流**推荐发布版**(Workflow.published_version,且确实已发布未退役)里的源头口径卡,一张卡一条。 + + 只读版本行、不查业务库、不调模型。推荐指针指不到一条已发布的版本(空指针、或指着已退役/没发布的)时**跳过这个 + 工作流**:宁可少自动一次,也不替它猜一版。""" + from sqlalchemy import select + + from app.apps.versions import is_published + from app.db.models import Workflow, WorkflowVersion + + rows = (await session.execute( + select(Workflow, WorkflowVersion) + .join(WorkflowVersion, WorkflowVersion.workflow_id == Workflow.id) + .where(WorkflowVersion.version == Workflow.published_version))).all() + out: list[dict[str, Any]] = [] + for workflow, row in rows: + if not is_published(row, current=workflow.published_version) or row.retired_at is not None: + continue + for node in (row.graph or {}).get("nodes") or []: + if not isinstance(node, Mapping) or node.get("type") != "metrics": + continue + data = node.get("data") if isinstance(node.get("data"), Mapping) else {} + config = data.get("config") if isinstance(data.get("config"), Mapping) else {} + if config.get("caliber_from") not in (None, "", {}): + continue + metrics = [dict(m) for m in config.get("metrics") or [] if isinstance(m, Mapping) and m.get("id")] + if not metrics: + continue + out.append({"workflow_id": workflow.id, "workflow_name": str(workflow.name or ""), + "version": int(row.version), "card_id": str(node.get("id") or ""), + "card_title": str(data.get("label") or node.get("id") or ""), + "caliber": str(config.get("caliber") or ""), "metrics": metrics}) + return out + + +def _auto_hinted(ref: Mapping[str, Any], question_norm: str) -> bool: + """这句话里点到了这个指标所在的工作流/口径/卡的名字(唯一提示用)。""" + for phrase in (ref.get("workflow_name"), ref.get("caliber"), ref.get("card_title")): + normalized = _normalize(phrase) + if len(normalized) >= 2 and normalized in question_norm: + return True + return False + + +def _auto_date_spans(text: str) -> list[tuple[int, int]]: + """原话里明确完整的单日/单月的位置(去掉它们之后剩下的才是业务语义)。和参数映射用的是同一批写法。""" + spans: list[tuple[int, int]] = [] + for pattern in (_AUTO_DAY_CN, _AUTO_DAY_DASH, _AUTO_MONTH_CN, _AUTO_MONTH_DASH): + spans += [(match.start(), match.end()) for match in pattern.finditer(text)] + return sorted(spans) + + +def _auto_remove_dates(text: str) -> str: + out, cursor = "", 0 + for start, end in _auto_date_spans(text): + if start < cursor: + continue # 重叠的取长的那一处 + out += text[cursor:start] + " " + cursor = end + return out + text[cursor:] + + +def _auto_trim(text: str) -> str: + """把通用疑问/查询/统计措辞从**两端**反复去掉(长词先去)。两端之外的一个字都不动。""" + out = text + changed = True + while changed and out: + changed = False + for phrase in _AUTO_FILLERS_SORTED: + if out.startswith(phrase): + out, changed = out[len(phrase):], True + if out.endswith(phrase): + out, changed = out[:-len(phrase)], True + return out + + +def _auto_remainder(question: str, hints: Sequence[str]) -> str: + """这句话剩下的**业务语义**(归一化后):去掉明确完整的日期/单月、句子里点到的口径/工作流/卡名(`提示的`), + 再去掉两端的通用问法、查询、统计措辞。剩下的必须和某个指标 name / 唯一 synonym **一字不差**才谈得上高置信。""" + norm = _normalize(_auto_remove_dates(question)) + for hint in sorted({_normalize(item) for item in hints}, key=len, reverse=True): + if len(hint) >= 2 and hint + "的" in norm: + norm = norm.replace(hint + "的", "") + return _auto_trim(norm) + + +def _auto_match(cards: Sequence[Mapping[str, Any]], remainder: str, question_norm: str) -> list[dict[str, Any]]: + """剩余业务语义与指标的 name / synonym **一字不差**才算命中;多一个字、少一个字都不算。 + + 指到不止一个指标(同名跨卡等)时用工作流/口径/卡的**唯一提示**收窄;收窄之后还是不止一个就交回空(回旧路径)。 + 不做模糊相似、不做包含匹配、不按整卡。""" + if len(remainder) < 2: + return [] + matched: dict[tuple[str, str, str], dict[str, Any]] = {} + for card in cards: + for metric in card["metrics"]: + if not any(_normalize(term) == remainder for term in _auto_metric_terms(metric)): + continue + matched[(card["workflow_id"], card["card_id"], str(metric["id"]))] = { + **card, "metric_id": str(metric["id"]), "metric": metric} + if len(matched) > 1: + marked = [ref for ref in matched.values() if _auto_hinted(ref, question_norm)] + return marked if len(marked) == 1 else [] + return list(matched.values()) + + +def _auto_hits(name: str, hints: Sequence[str]) -> bool: + """字段名命中了哪一类提示:ASCII 提示按词边界比(total 不算 to),中文提示按子串比。""" + lowered = str(name or "").lower() + for hint in hints: + if hint.isascii(): + if re.search(rf"(?:^|[^a-z]){re.escape(hint)}(?:[^a-z]|$)", lowered): + return True + elif hint in lowered: + return True + return False + + +def _auto_interval_fields(fields: Sequence[Mapping[str, Any]]) -> tuple[str | None, str | None]: + """入口字段里配对的那个开始/结束日期字段:各只有一个、名字不重、类型承载得了 ISO 日期才算,否则不算(不猜)。""" + from app.ledger import params + + starts: list[str] = [] + ends: list[str] = [] + for field in fields: + name = str(field.get("name") or "").strip() + if not name or params.field_type(field) not in _AUTO_DATE_TYPES: + continue + is_start = _auto_hits(name, _AUTO_START_HINTS) + is_end = _auto_hits(name, _AUTO_END_HINTS) + if is_start == is_end: + continue # 都不像、或又像开始又像结束(起止时间):不拿来配对 + (starts if is_start else ends).append(name) + if len(starts) == 1 and len(ends) == 1 and starts[0] != ends[0]: + return starts[0], ends[0] + return None, None + + +def _auto_date_interval(text: str) -> tuple[str, str] | None: + """原话里明确完整的单日/单月 → 半开区间 (含, 不含)。 + + 单日 `2026-10-01` / `2026年10月1日` → [当天, 次日);单月 `2026-10` / `2026年10月` → [当月 1 日, 次月 1 日)。 + 别的(「上个月」「上个季度」「最近一周」)都交回 None——相对说法要按当下时刻算,这里不替它算。""" + day = _AUTO_DAY_CN.search(text) or _AUTO_DAY_DASH.search(text) + if day is not None: + try: + start = date(int(day.group(1)), int(day.group(2)), int(day.group(3))) + except ValueError: + return None + return start.isoformat(), date.fromordinal(start.toordinal() + 1).isoformat() + month = _AUTO_MONTH_CN.search(text) or _AUTO_MONTH_DASH.search(text) + if month is not None: + year, number = int(month.group(1)), int(month.group(2)) + if not 1 <= number <= 12: + return None + first = date(year, number, 1) + after = date(year + 1, 1, 1) if number == 12 else date(year, number + 1, 1) + return first.isoformat(), after.isoformat() + return None + + +def _auto_inputs(selected: Any, text: str) -> dict[str, Any] | None: + """这次要交给 QueryCore 的入口取值:能拿全(含声明的缺省值)且过得去真实校验才交回,否则 None。 + + 用派生收窄出来的**这次真正会用到的**入口字段与取数节点判,和 querycore 执行时同一套:`params.resolve` 定值(显式 + 非空优先、否则声明缺省值)、`params.check_nodes` 判完整性/承载、`apps.forms.validate_form` 判必填与类型。任何一处 + 过不去就交回 None——缺不能确定的日期或非日期必填值都回旧路径,绝不带着不确定的参数去执行。""" + from app.apps.forms import input_schema, validate_form + from app.ledger import params + + fields = [dict(f) for f in selected.entry_fields] + inferred: dict[str, Any] = {} + interval = _auto_date_interval(text) + if interval is not None: + start_field, end_field = _auto_interval_fields(fields) + if start_field is None or end_field is None: + return None # 有明确日期,却没有能配对的开始/结束字段:不猜 + inferred[start_field], inferred[end_field] = interval + values = params.resolve(fields, inferred) + if params.check_nodes(selected.fetches, fields=fields, values=values, + where="自动路由的入口声明的字段"): + return None + if validate_form(input_schema(fields), values): + return None + return values + + +def _permitted(allowed: Any) -> set[tuple[str, int]] | None: + """调用方给的授权范围归一化:`(workflow_id, version)` 的集合(或 dict 的键,usable_calibers 就是那种字典)。 + + None 表示**调用方已显式放行**(搭建者 / admin / 关登录):它们本来就能直接按口径执行,不按资产授权收窄。认不出来 + 的条目直接跳过——授权信息读不出来的那一条不当成有权。""" + if allowed is None: + return None + keys = allowed.keys() if isinstance(allowed, Mapping) else allowed + out: set[tuple[str, int]] = set() + for item in keys or (): + if isinstance(item, str) or not isinstance(item, Sequence) or len(item) != 2: + continue + workflow_id, version = item + try: + out.add((str(workflow_id), int(version))) + except (TypeError, ValueError): + continue + return out + + +async def auto_route(session: Any, *, question: str, purpose: str | None = None, + allowed: Any = None) -> Route | None: + """普通问数的**保守默认路由**:高置信确定的请求交回一条可以直接交给固定执行的请求,否则 None。 + + 只在下面每一件都说得清时才命中:按推荐发布版的指标 name / 唯一 synonym 规范化精确匹配**唯一**一个指标(跨卡同名或 + 一句指到不止一个就不自动);这句话没有含糊的业务条件、也没有和那次口径声明的算法对不上;派生出来的这次入口取值 + 拿得全、类型可证。任何一处不确定(含指不到、派生不出、版本没发布)都交回 None——调用方原样走旧的 Agent 路径, + 不向用户多说什么、也不替它挑一份口径。**零模型**:只看库里的发布版与图,不问模型也不做模糊相似。 + + `allowed` 是这个人能用的 `(workflow_id, version)` 集合(资产授权,见 `_permitted`):匹配照旧按**全部发布口径**看, + 所以「没匹配到」和「命中了但没权」分得开——唯一命中却不在 allowed 里交回**终止型**的 `ROUTE_REFUSED` / + `ROUTE_NOT_PERMITTED`,调用方照实说没有授权,**不回退旧的 Agent 路径**(那条路会去翻底表)。allowed 为 None 是调用方 + 已放行(搭建者及以上),不做这道闸。歧义、参数不全、没匹配到仍然交回 None,由调用方走旧路。""" + from app.ledger import derive, querycore + + text = str(question or "").strip() + if not text: + return None + purpose = str(purpose or querycore.DEFAULT_PURPOSE) + permitted = _permitted(allowed) + cards = await _auto_cards(session) + hints = [item for card in cards for item in (card["workflow_name"], card["caliber"], card["card_title"])] + candidates = _auto_match(cards, _auto_remainder(text, hints), _normalize(text)) + if len(candidates) != 1: + return None + chosen = candidates[0] + # 授权闸在最前面:唯一命中但这个人的授权范围里没有这一版时,结果只能是「没授权」,不能落到下面任何一条会把这句话 + # 交给旧 Agent 路径(去翻底表)的分支上 + if permitted is not None and (str(chosen["workflow_id"]), int(chosen["version"])) not in permitted: + return Route(ROUTE_REFUSED, ROUTE_NOT_PERMITTED, NOT_PERMITTED) + # 含糊业务条件、或和这次口径声明的算法对不上:都不自动(交给旧路径,不在这里澄清、不改口径) + ignore = _metric_mentions(chosen["metrics"]) + matches, clarifications = match_conditions(text, ignore=ignore) + if clarifications: + return None + if matches and _condition_problem(matches, chosen["metrics"]) is not None: + return None + # 这次入口取值:按派生收窄出来的字段与节点判,拿不全就不自动 + try: + pinned = await derive.read_pinned(session, chosen["workflow_id"], chosen["version"], chosen["card_id"]) + selected = derive.select_pinned(pinned, metric_ids=[chosen["metric_id"]]) + except derive.NotDerivable: + return None + inputs = _auto_inputs(selected, text) + if inputs is None: + return None + return Route(ROUTE_EXECUTE, ROUTE_AUTO, + f"自动命中固定口径「{chosen['caliber'] or chosen['card_title']}」的指标,直接按固定口径执行,不重复解析/规划", + request={"workflow_id": chosen["workflow_id"], "card_id": chosen["card_id"], + "metric_ids": [chosen["metric_id"]], "inputs": inputs, + "version": chosen["version"], "purpose": purpose}) + + +__all__ = ["KIND_AMBIGUOUS", "KIND_MISSING", "KIND_NO_MATCH", "NOT_PERMITTED", "PROPOSAL_AMBIGUOUS", + "PROPOSAL_NONE", "ROUTE_AMBIGUOUS", "ROUTE_AUTO", "ROUTE_CLARIFY", "ROUTE_CONDITION_MISMATCH", + "ROUTE_EXECUTE", "ROUTE_EXPLORE", "ROUTE_METRICS_REQUIRED", "ROUTE_NO_CALIBER", "ROUTE_NOT_PERMITTED", + "ROUTE_READY", "ROUTE_REFUSED", "ROUTE_VERSION_INVALID", "Clarification", "FieldMatch", "Proposal", + "Route", "auto_route", "declared_capabilities", "from_model", "match_conditions", "preview", "propose", + "route"] diff --git a/backend/app/ledger/params.py b/backend/app/ledger/params.py new file mode 100644 index 00000000..01e7e61d --- /dev/null +++ b/backend/app/ledger/params.py @@ -0,0 +1,669 @@ +"""SQL 模板参数完整性:一处认模板里的参数,各入口同一套语义(开工任务书 v3 · K01,§4.4 参数完整性)。 + +**一条规则,几个入口。** 口径的取数 SQL 模板里参数写成 `{{ input.字段 }}`。试跑(api/ledger 的 trial,含草稿试跑)、 +组合式问数(ledger/compose)、派生图(ledger/derive 的 probe / reconcile / recall)和运行时的数据源查询 +(engine/nodes/tools.run_tool)都按这里的一套判断:**缺参数、未声明参数、认不出的写法,在渲染之前就拒,绝不发出一条 +少了个值的 SQL**(以前 `{{ input.store }}` 取不到值时渲染成空串,`AND region = ''` 照样发出去)。 + +正式出具(ledger/issue)与召回计划(ledger/recall)都接了这里的参数完整性(check_nodes:issue 在代填之前拒、 +recall 在计划这一步判「这一组重算得了吗」),并且各留了一把自己的分寸(issue 跳过认不出写法的取数模板、 +recall 两版各自判)。 + +| 情况 | 行为 | +| --- | --- | +| 必需参数没给值、也没有缺省值 | missing_parameter | +| 可选参数没给值、也没声明的缺省值 | missing_parameter(不能当空串) | +| 显式给了空串、字段也没声明的缺省值 | missing_parameter——空串不是值,是省略(入口收值 provided 与运行时的存在性判断同一套) | +| SQL 引用了入口没声明的字段 | undeclared_parameter | +| 参数写在表名、列名里,或用了倒推不出值的写法(vars.、模板函数、别的过滤器) | unsupported_parameter | +| 引号里的值带引号 / 反斜杠 / 换行,裸写的不是数,注释里的不能带换行或 `*/` | literal_unsupported | +| 可选参数声明了缺省值(含 `""`:作者写的就是「空值不过滤」) | 按缺省值渲染,不算缺参数 | + +(还有一层在图那边:engine/variables 会拦「引用了没人产出的 `{{ input.x }}`」的节点,那一条在运行发起前就红——组合式问数 +拷进来的节点因此**保留不了模板**,只能渲染成字面语句 + 这里的参数契约;那条校验按同一份契约跳过 args / sql,见下。) + +**运行时的兜底认哪些写法。** 取数 SQL 在发出之前按 `input` 引用过一遍参数完整性,认法和 +engine/expressions.resolve_path 一致:`input.字段`、`input['字段']`、`input["字段"]`、`input[0]`、 +`input.rows[0].name` 都算,取的是第一层的那个字段(下标里的字是字面量,resolve_path 取的就是字面量)。认不出取哪个 +字段的写法——光秃秃的 `{{ input }}`、`input['a.b']`、`input[a[b]]`、`input x`——resolve_path 取不到值、会渲染成空串, +SQL 执行路径按 unsupported_parameter 直接拒,不当「没引用参数」放过去。vars. / nodes. 这些别的命名空间不在这趟里 +(照旧由画布的变量校验管);口径模板那边的严格解析(slots_of,只认 `{{ input.字段 }}`)没有变。 + +**这次的值怎么定(resolve)。** 显式给的(不是 None、不是空串)优先,否则用声明的缺省值——`default` 给了就用,**含 `0` +与空串**(`resolve`);检查、渲染、快照材料里的输入哈希用的都是这一份。已经自己补过缺省值的入口(试跑、组合式问数)传进来 +的就是补好的 values,结果不变;`plan()` 这条共享层接口按这一份定值:字段声明了 `default="east"` 而调用方没给值时,渲染出来 +的是 `east`,不是空串(`default=0` 同理,渲染出来是 `0`)。 + +**值只当数据,只经历一次模板替换。** 本仓库的数据源适配器是「内联文本替换」:值渲染进语句文本,没有驱动级参数绑定 +(ADAPTER = "inline_text",快照里照实写,不假装是驱动绑定)。所以值必须**只被模板替换一次**——渲染进模板的那一次;渲染 +出来的结果不会再被当模板解释(`{{ vars.x }}` 这样的文本落在值里就是字面量)。为此: + +- 组合式问数(ledger/compose)在拷节点时把值渲染进 SQL(只有这一次),同时在节点上写一份参数契约(见 marker): + args 里已经是字面语句,运行时(engine/nodes/tools.run_tool)的模板渲染一概不碰它——不然值里的 `{{ vars.question }}` + 会在运行时被当成模板替换成那个变量的值,SQL 被数据改掉; +- 对账图里「这次的取数」放进去的是**执行过的 SQL 原文**;按维度值对齐的合并语句(ledger/reconcile.align_sql)是服务端 + 按查询结果拼的字面 SQL:两处都写 marker,运行时的模板渲染一概不碰它们(tools.run_tool / merge.run_merge); +- 画布校验(engine/variables)按 literal_keys 跳过带契约节点的 args / sql:里面是数据,不按变量引用判——否则值里恰好 + 有几个花括号,就等于那张图跑不起来。 + +**参数契约(marker)与它注解的那条语句绑定。** 写进节点 `data.config[KEY]` 的那一份记:承载方式(内联)、**rendered_hash** +(它注解的那一项——tool 的 `args`、merge 的 `sql`——的确定哈希)、源模板哈希、规范化输入哈希、参数契约(字段、类型、 +缺省值)与每个参数写在哪儿(quoted / bare / comment)、出处。绑定值不另存一份:它就是内联进实际执行语句里的那些字,实际 +语句(payload["sql"])本身落进快照,展示用 SQL 不作为执行证明。 + +**哈希对不上,契约就作废。** 节点会被复制、会被改:改过 args / sql 之后,契约说的已经不是这一条语句了。所以 +`literal_keys()` 一律先核对 rendered_hash——对得上才跳过渲染、才跳过画布校验的模板扫描、才把契约材料记进快照;对不上 +(复制后改了、改回普通模板、只是改了个别的参数)就当**没写契约**:正常渲染、正常判参数,画布的变量校验也照常扫。 +绝不能因为节点上留着一份旧契约,就把改过的、带 `{{ }}` 的语句原样发出去。 + +**快照材料**里的源模板正文不写:engine/variables 会把节点配置里每一段带 {{ }} 的字都当活引用扫,正文留在节点上会把取数 +模板的占位符报成「没有任何节点产出」。出处(source)记的是那一版取数节点的固定引用,**本切片只把它当地址写下来**——没有 +实现「按引用自动还原模板并核对哈希」,要复核得照着这个引用去读那一版。 + +**还没做的**(照实说,不当成已完成):驱动级参数绑定(占位符交给驱动、绑定值单独传)只对试点方言有意义,本切片没有 +实现,所以含引号、反斜杠、换行的值仍然明确拒绝(literal_unsupported),不能因此宣布特殊字符与各类型都已支持;类型契约 +只做到规范化声明类型和值类别(R02 那类「同名字段声明成不同数字类型怎么合并」的规则在 ledger/draftplan._merged_type, +不在这里)。 +""" +from __future__ import annotations + +import hashlib +import json +import re +from collections.abc import Iterable, Mapping, Sequence +from dataclasses import dataclass, field +from typing import Any + +#: 参数问题的机器码(§4.4 的三条 + 值承载不了的一条) +MISSING = "missing_parameter" +UNDECLARED = "undeclared_parameter" +UNSUPPORTED = "unsupported_parameter" +LITERAL = "literal_unsupported" + +CODES = (MISSING, UNDECLARED, UNSUPPORTED, LITERAL) + +#: 承载参数的方式:驱动不提供参数绑定,值一律内联进语句文本(旧适配器)。快照按它照实写 +ADAPTER = "inline_text" + +#: 节点配置里写参数契约的键(ledger/compose、ledger/derive、ledger/reconcile 写,engine 侧按它认) +KEY = "parameters" +#: args / sql 里已经是渲染好的字面语句(值渲染进去的那一次已经发生过):运行时的模板渲染不再碰它 +LITERAL_ARGS = "literal" +#: 契约里记的、它注解的那一项(tool 的 args / merge 的 sql)的确定哈希:对不上就说明契约过时了 +HASH_KEY = "rendered_hash" +#: 带参数契约的节点上,「已经渲染成字面值」的那一项在哪个键上(按节点类型):调用工具的 args、合并查询的 sql。 +#: engine/variables 扫模板引用、engine/nodes/* 渲染参数时都要跳过它们——里面是数据,不是活模板 +LITERAL_KEY = {"tool": "args", "merge": "sql"} + +#: 运行时查询快照记参数材料时,ToolContext.extra 里用的键(tools/datasource 读) +SNAPSHOT_KEY = "sql_parameters" + +#: 值写在哪儿(data/sql_semantics._template_slots 的 context):引号里的字 / 裸写 / 注释里 / 表名列名 +CONTEXTS = ("quoted", "bare", "comment", "name") +#: 参数能带的过滤器(和 data/sql_semantics._SLOT_FILTERS 同一份):别的过滤器倒推不回值 +FILTERS = frozenset({"trim", "compact"}) + +#: 写给人和模型的几句话(各入口同一句,改就一处改) +MISSING_TEXT = "参数「{name}」这次没有值:{where}没给值、也没有缺省值,不能当空串用(missing_parameter)" +UNDECLARED_TEXT = "SQL 模板引用了没有声明的参数「{name}」:{where}是 {fields}(undeclared_parameter)" +UNSUPPORTED_TEXT = "SQL 模板里的参数认不出来:{reason}(unsupported_parameter)" +#: 引用了入口、但看不出取的是哪个字段的写法:resolve_path 取不到值 → 会渲染成空串,SQL 执行路径照实拒 +DYNAMIC_TEXT = ("SQL 模板里的入口引用「{{{{ {expr} }}}}」看不出取的是哪个字段(这样写会渲染成空串):" + "请写成 {{{{ input.字段 }}}},点号与 {{{{ input['字段'] }}}} 都行,下标里要是字面量(unsupported_parameter)") +QUOTED_TEXT = "参数「{name}」写在 SQL 的引号里,值里不能有引号、反斜杠或换行(literal_unsupported)" +BARE_TEXT = "参数「{name}」直接写在 SQL 里(没有引号),只能是数,当前为「{value}」(literal_unsupported)" +COMMENT_TEXT = "参数「{name}」写在 SQL 的注释里,值里不能有换行或注释结束符(literal_unsupported)" +#: 取数模板根本读不出来(模板语法、引号没配对上)时套在原因外面的那一句 +UNREADABLE_TEXT = "取数节点的 SQL 模板认不出参数写在哪:{reason}" + +_NUMBER = re.compile(r"^\s*-?\d+(?:\.\d+)?\s*$") +#: 运行时按它挑出模板里的 input 引用(宽松:只认 {{ input.字段 }},别的模板写法不归参数完整性管) + + +class ParameterRefused(Exception): + """参数不合规:不渲染、不发 SQL。problems 给程序认(机器码),message 给人看。""" + + def __init__(self, problems: Sequence[Problem]) -> None: + self.problems = tuple(problems) + super().__init__(describe(self.problems)) + + @property + def code(self) -> str: + return self.problems[0].code if self.problems else UNSUPPORTED + + @property + def message(self) -> str: + return str(self) + + +@dataclass(frozen=True) +class Slot: + """模板里的一处 `{{ input.字段 }}`:第几处、字段、过滤器、写在哪儿。""" + + index: int + field: str + filters: tuple[str, ...] = () + context: str = "bare" + + def as_dict(self) -> dict[str, Any]: + return {"name": self.field, "filters": list(self.filters), "slot": self.context} + + +@dataclass(frozen=True) +class Problem: + """一处参数问题:机器码 + 给人看的一句话(含节点,便于在画布上定位)。""" + + code: str + message: str + name: str | None = None + node_id: str | None = None + where: str | None = None + + def as_dict(self) -> dict[str, Any]: + return {"code": self.code, "name": self.name, "node_id": self.node_id, "message": self.message} + + +@dataclass(frozen=True) +class Statement: + """一次取数的结果:渲染好的字面语句 + 进查询快照的参数材料(源模板、两种哈希、参数类型与写在哪儿)。""" + + statement: str + material: dict[str, Any] = field(default_factory=dict) + + def __str__(self) -> str: # pragma: no cover - 只为人读 + return self.statement + + +def describe(problems: Iterable[Problem]) -> str: + """几处问题合成一句话(给人和模型看的那句)。""" + return ";".join(p.message for p in problems) + + +# ========================================================================== +# 认得模板里的参数 +# ========================================================================== + + +def slots_of(template: str) -> tuple[Slot, ...]: + """模板里每一处 `{{ input.字段 }}`(含写在哪儿、带了什么过滤器)。认不出写法、写在表名列名里的抛 + ParameterRefused(unsupported_parameter)——判断和带值比对那一套(data/sql_semantics._template_slots)是同一份。""" + from app.data.sql_semantics import _NotComparable, _template_slots + + try: + spans, _ = _template_slots(template) + except _NotComparable as e: + raise ParameterRefused([Problem(UNSUPPORTED, str(e))]) from None + return tuple(Slot(index=s.index, field=s.field, filters=tuple(s.filters), context=s.context) for _, _, s in spans) + + +def input_refs(template: str) -> tuple[str, ...]: + """模板里按 input 取值、而且**认得出取的是哪个字段**的那些引用,按出现先后去重。 + + 认法和 engine/expressions.resolve_path 一个走法:`input.字段`、`input['字段']`、`input["字段"]`、`input[0]`、 + `input.rows[0].name` 都算(下标里的字是字面量——resolve_path 取的就是字面量,不做表达式求值),取的是第一层的 + 那个字段。非 input 的模板写法(vars.、nodes.、模板函数的具体实现)不归这里管:普通画布上的取数 SQL 照样能引用 + 运行时的值。 + + 认不出的写法(`{{ input }}`、`input['a.b']`、`input[a[b]]`……)**不在这里**——它们取不到值、会渲染成空串,由 + dynamic_input_writings 交出来,SQL 执行路径按 unsupported_parameter 拒。""" + return tuple(dict.fromkeys(field for field in _input_fields(template) if field)) + + +def dynamic_input_writings(template: str) -> tuple[str, ...]: + """模板里引用了 input、但**认不出取的是哪个字段**的写法,原样一份(按出现先后去重)。 + + resolve_path 对这些写法取不到值(返回 None),模板渲染出来是空串:SQL 执行路径不能把它当「没引用参数」放过去。""" + return tuple(dict.fromkeys(writing for _, writing in _scanned_inputs(template) if writing)) + + +def mentions_input(template: str) -> bool: + """模板里有没有按 input 取值的地方(认得出的与认不出的都算):SQL 执行路径按它决定要不要过参数完整性。""" + return bool(input_refs(template) or dynamic_input_writings(template)) + + +#: 模板里一处 {{ … }}(和 engine/expressions 的 _TEMPLATE_RE 同一个写法) +_TEMPLATE_EXPR = re.compile(r"\{\{(.*?)\}\}", re.DOTALL) +#: 路径的一段:名字 + 若干 [下标](和 engine/expressions.resolve_path 同一个写法) +_SEGMENT = re.compile(r"^([^\[\]]*)((?:\[[^\[\]]+\])*)$") +_INDEX = re.compile(r"\[([^\[\]]+)\]") +#: 表达式开头是不是 input 这个命名空间(`input.x` / `input['x']` / `input[0]` / 光秃秃的 `input`)。 +#: 用词边界:`inputs`、`input_value` 这类别的名字不算。写成 `input x` 这种(以 input 起头但合不上路径走法) +#: 也归到这里,由 _scanned_inputs 判成「认不出取哪个字段」——resolve_path 对它同样取不到值。 +_INPUT_HEAD = re.compile(r"^input\b") + + +def _lookups(path: str) -> list[str] | None: + """按 resolve_path 的走法把一条路径拆成一层层的取法(名字 / 下标里的字),写不进那套写法返回 None。 + + resolve_path 是「按点切段、每段再拆名字与若干下标」,认不出的一段就整个取不到值——这里逐字照搬那一套, + 所以「这里认得出」= 「resolve_path 取得到值」。""" + out: list[str] = [] + for raw in path.split("."): + raw = raw.strip() + if not raw: + continue + m = _SEGMENT.match(raw) + if m is None: + return None + name, idx_part = m.group(1).strip(), m.group(2) + if name: + out.append(name) + out += [idx.strip().strip("'\"") for idx in _INDEX.findall(idx_part)] + return out + + +def _template_path(expr: str) -> str: + """一处 `{{ … }}` 里的路径部分(去掉过滤器);模板函数按它的第一个参数认(同 engine/variables._root_of)。""" + from app.engine.expressions import template_call + + path = expr.split("|")[0].strip() + if "(" in path and (call := template_call(path)) is not None: + return call[1][0] if call[1] else "" + return path + + +def _scanned_inputs(template: str) -> list[tuple[str, str]]: + """模板里每一处按 input 取值的地方:[(字段名, 认不出的原样写法)],两者只有一个非空。 + + 认得出字段的给 (字段名, "");认不出取哪个字段的(会渲染成空串)给 ("", 那处表达式原文)。**范围是「以 input 起头的 + 那几条路径」**:不是 input 的引用(vars.、nodes.、别的模板函数、别的根名字)两边都空,不在这趟里——那些由画布的 + 变量校验管,取数 SQL 照旧能引用它们。""" + out: list[tuple[str, str]] = [] + for m in _TEMPLATE_EXPR.finditer(template or ""): + expr = m.group(1).strip() + path = _template_path(expr) + if not path or not _INPUT_HEAD.match(path): + continue + lookups = _lookups(path) + if lookups is None or lookups[0] != "input" or len(lookups) < 2: + # 认不出取的是哪个字段(写法不合 resolve_path、或者就是光秃秃的 {{ input }}):会渲染成空串 + out.append(("", expr or path)) + continue + out.append((lookups[1], "")) + return out + + +def _input_fields(template: str) -> list[str]: + return [field for field, _ in _scanned_inputs(template)] + + +def declared(fields: Iterable[Mapping[str, Any]]) -> dict[str, dict[str, Any]]: + """入口字段 → {字段名: 字段(原样的一份)}。没名字的不要;同名的取第一个(和 derive.entry_fields 一个认法)。""" + out: dict[str, dict[str, Any]] = {} + for f in fields: + name = f.get("name") + if isinstance(name, str) and name.strip(): + out.setdefault(name.strip(), dict(f)) + return out + + +#: 声明类型 → 规范类型。认不出的一律 string(各入口同一套:类型判定不依赖字段先后,R02 的一半) +_TYPES = {"string": "string", "text": "string", "integer": "integer", "int": "integer", "number": "number", + "float": "number", "boolean": "boolean", "bool": "boolean", "date": "date", "datetime": "datetime", + "time": "time", "file": "file", "array": "array", "object": "object"} + + +def field_type(field: Mapping[str, Any]) -> str: + """字段声明的参数类型,规范成一个词。没写、认不出的按 string(不按值反推:同一个值在不同字段上含义不同)。""" + return _TYPES.get(str(field.get("type") or "").strip().lower(), "string") + + +def value_kind(value: Any) -> str: + """这次的实际值是什么类别:text / number / boolean / null / list / object。""" + if value is None: + return "null" + if isinstance(value, bool): + return "boolean" + if isinstance(value, (int, float)): + return "number" + if isinstance(value, str): + return "text" + if isinstance(value, (list, tuple)): + return "list" + if isinstance(value, Mapping): + return "object" + return type(value).__name__ + + +def _names(names: Iterable[str]) -> str: + items = list(names) + return "、".join(items) if items else "(没有入口字段)" + + +def _given(value: Any) -> bool: + """这个值算不算「给了」:None 与空串都不算——空串不是值,是省略。三处按同一份判:入口收值(provided)、 + 缺参数判断(_unresolved / runtime_problems)、渲染前定值(resolve)。""" + return value is not None and value != "" + + +def provided(values: Mapping[str, Any]) -> dict[str, Any]: + """用户这次「给了值」的那些键:None 和空串都算没给——空串不是值,是省略。 + + 各入口收值用同一份(试跑 api/ledger.trial_caliber、草稿试跑、组合式问数 compose.check_inputs):显式传了 `""`、 + 字段又没声明缺省值时,接着判就是 missing_parameter(不能当空串用);字段声明了 `default=""`(作者写的就是「空值不过滤」) + 的照缺省值渲染,不算缺(见 _unresolved)。""" + return {str(k): v for k, v in values.items() if _given(v)} + + +def resolve(fields: Iterable[Mapping[str, Any]], values: Mapping[str, Any]) -> dict[str, Any]: + """这次要渲染进去的那一份值:**显式给的(不是 None、不是空串)优先,否则用声明的缺省值**(`default` 给了就用—— + 含 `0` 与空串)。 + + 共享层替入口把这一份定下来:检查、渲染、快照的输入哈希都用它。字段声明了 `default="east"` 而调用方没给值时,渲染出来 + 的必须是 `east`——以前 plan() 直接拿原来的 values 渲染,声明了却渲染成空串。已经自己补过缺省值的入口(组合式问数、 + 试跑)传进来的就是补好的 values,这里不改变它们的结果;入口没声明的键(开放入口:值由发起时传)原样留着。 + """ + out = provided(values) + for name, field in declared(fields).items(): + if name in out: + continue # 显式给了非空值:以它为准 + default = field.get("default") + if default is not None: + out[name] = default # 否则用声明的缺省值(0 / 空串也算声明过的) + return out + + +def _written(value: Any) -> str: + if isinstance(value, str): + return value + if isinstance(value, (dict, list)): + return json.dumps(value, ensure_ascii=False, default=str) + return str(value) + + +def _unresolved(name: str, field: Mapping[str, Any] | None, values: Mapping[str, Any]) -> bool: + """这个参数这次没有可用的值:没给、给了 None、或者给了空串(空串不是值,是省略——和入口收值 params.provided 同一套), + 而且声明的缺省值也是 None。 + + 声明了缺省值的算「按声明省略」,不算缺——含 `""`:作者写的就是「空值不过滤」(`AND ('{{ input.x }}' = '' OR …)`), + 那是声明的省略规则,不是没给值。""" + if _given(values.get(name)): + return False + return (field or {}).get("default") is None + + +# ========================================================================== +# 判断:模板、值 +# ========================================================================== + + +def literal_problem(name: str, value: Any, contexts: Iterable[str]) -> str | None: + """值写在 SQL 的哪个位置、旧适配器(内联文本替换)承载得了吗:承载不了给一句原因,承载得了为 None。 + + 引号里的字里再出现引号 / 反斜杠 / 换行、裸写的位置上不是数、注释里带换行或注释结束符——这些都会让渲染出来的语句 + 不再等于「那一版口径的 SQL」。真支持特殊字符要等驱动级参数绑定(见模块说明),那之前明确拒绝,不硬塞。""" + text = _written(value) + where = set(contexts) + if "quoted" in where and any(ch in text for ch in ("'", "\\", "\n", "\r")): + return QUOTED_TEXT.format(name=name) + if "bare" in where and not (isinstance(value, (int, float)) and not isinstance(value, bool)) \ + and not (isinstance(value, str) and _NUMBER.match(value)): + return BARE_TEXT.format(name=name, value=text[:40]) + if "comment" in where and ("\n" in text or "\r" in text or "*/" in text): + return COMMENT_TEXT.format(name=name) + return None + + +def check_template(template: str, *, fields: Mapping[str, Mapping[str, Any]], values: Mapping[str, Any] | None = None, + node_id: str | None = None, where: str = "入口字段") -> list[Problem]: + """一条取数模板按声明的入口字段过一遍:未声明、认不出的写法;给了 values 的,再判缺值与值承载不了。 + + values 为 None 是「此刻还没有这次调用的值」(读一版口径时就是这样):只判模板和声明对不对得上。 + 认不出写法(unsupported)时不接着往下判——值写在哪儿都还没定,别的结论不可靠。""" + try: + slots = slots_of(template) + except ParameterRefused as e: + return [Problem(UNSUPPORTED, UNREADABLE_TEXT.format(reason=p.message), node_id=node_id) for p in e.problems] + problems: list[Problem] = [] + seen: set[str] = set() + for slot in slots: + name = slot.field + if name in seen: + continue + seen.add(name) + field = fields.get(name) + if field is None: + problems.append(Problem(UNDECLARED, UNDECLARED_TEXT.format(name=name, where=where, + fields=_names(fields)), + name=name, node_id=node_id, where=where)) + elif values is not None and _unresolved(name, field, values): + problems.append(Problem(MISSING, MISSING_TEXT.format(name=name, where=where), + name=name, node_id=node_id, where=where)) + if values is None: + return problems + seen_literal: set[str] = set() + for name in (s.field for s in slots): + field = fields.get(name) + if field is None or name not in values or name in seen_literal: + continue + seen_literal.add(name) + # 同一个字段的每一处槽位一起判(写在引号里 / 裸写 / 注释里各算一处),一个字段只报一条 + if problem := literal_problem(name, values[name], (s.context for s in slots if s.field == name)): + problems.append(Problem(LITERAL, problem, name=name, node_id=node_id, where=where)) + return problems + + +def _sql_of(node: Mapping[str, Any]) -> str | None: + args = ((node.get("data") or {}).get("config") or {}).get("args") if isinstance(node, Mapping) else None + sql = args.get("sql") if isinstance(args, Mapping) else None + return sql if isinstance(sql, str) and sql else None + + +def check_nodes(nodes: Iterable[Mapping[str, Any]], *, fields: Iterable[Mapping[str, Any]], + values: Mapping[str, Any] | None = None, where: str = "入口字段") -> list[Problem]: + """几个调用工具节点(原始 JSON)的 args.sql 各过一遍,问题按节点先后合起来。values 不给就只判模板与声明。""" + declared_fields = declared(fields) + out: list[Problem] = [] + for node in nodes: + if not isinstance(node, Mapping): + continue + sql = _sql_of(node) + if sql is None: + continue + out += check_template(sql, fields=declared_fields, values=values, node_id=str(node.get("id") or "") or None, + where=where) + return out + + +def runtime_problems(template: str, *, values: Mapping[str, Any], + declared: Mapping[str, Mapping[str, Any]]) -> list[Problem]: + """运行时的同一条判断(宽松认法):模板里按 input 取值的地方这次取不到值就拒。 + + 认法和 engine/expressions.resolve_path 一致(`input.字段`、`input['字段']`、`input[0]`、`input.a.b[0].c` 都算, + 取的是第一层的字段);认不出取哪个字段的写法(`{{ input }}`、`input['a.b']`、`input[a[b]]`)同样拒——它们渲染成 + 空串,不能当「没引用参数」放过去。 + + 「有值」和入口收值(params.provided)同一套:**None 和空串都算没给**(空串不是值,是省略),取到别的值才放行。 + 开放入口(入口节点没声明字段、键由发起时传)也一样——否则 `{{ input['store'] }}` 传了个空串就会渲染成 `''`, + 发出一条 `AND region = ''`。 + + - 没给值、入口也没声明过它 → undeclared_parameter; + - 没给值、声明过、声明的缺省值也是 None(含只声明成可选的)→ missing_parameter;声明了缺省值(含 `""`:作者写的 + 就是「空值不过滤」)的按声明保留,照缺省值渲染。 + 只看会不会渲染成空串:普通画布上的取数 SQL 引用 vars./nodes. 的不归它管。 + """ + problems: list[Problem] = [ + Problem(UNSUPPORTED, DYNAMIC_TEXT.format(expr=writing)) for writing in dynamic_input_writings(template)] + for name in input_refs(template): + if _given(values.get(name)): + continue + field = declared.get(name) + # 这次运行的输入里有这个键(只是值空着)就不算「没声明」——那是这次没给值;连键都没有、入口也没声明才是没声明 + if field is None and name not in values: + problems.append(Problem(UNDECLARED, UNDECLARED_TEXT.format( + name=name, where="这次运行的入口", fields=_names(sorted(declared))), name=name)) + elif _unresolved(name, field, values): + problems.append(Problem(MISSING, MISSING_TEXT.format(name=name, where="这次运行的入口"), name=name)) + return problems + + +# ========================================================================== +# 渲染与快照材料 +# ========================================================================== + + +def render(template: str, values: Mapping[str, Any]) -> str: + """模板按值渲染成字面语句。走的是运行时同一个渲染器(engine/expressions.render_template):值替换进来就不再被 + 模板解释一遍。这里只负责「值是我的、模板只过一次」,缺值缺声明的判断在 check_* / plan。""" + from app.engine.expressions import render_template + + return render_template(template, {"input": dict(values)}) if "{{" in template else template + + +def _hash(text: str) -> str: + return hashlib.sha256(text.encode("utf-8")).hexdigest() + + +def material(template: str, *, values: Mapping[str, Any], declared_fields: Mapping[str, Mapping[str, Any]], + source: Mapping[str, Any] | None = None, with_template: bool = True) -> dict[str, Any]: + """查询快照要记的那一份:源模板、源模板哈希、规范化输入哈希、参数契约、每个参数的类型与写在哪儿、承载方式。 + + 绑定值不在这里再存一份——内联方式下它就写在实际执行语句里,而实际语句本身在快照里(payload["sql"])。 + + with_template=False 时不写源模板正文,只留哈希(写进节点配置的那一份就是这样:engine/variables 会把节点配置里 + 每一段带 {{ }} 的字都当成活引用扫一遍,正文留在节点上会把取数模板的占位符报成「没人产出」)。这一版口径的模板由 + source 里的固定引用(工作流 + 版本 + 节点)还原,哈希用来核对还原出来的还是不是当时那一份。""" + names = input_refs(template) + bound: list[dict[str, Any]] = [] + try: + by_field = {s.field: s.context for s in slots_of(template)} + except ParameterRefused: + by_field = {} + for name in names: + field = declared_fields.get(name) or {} + item: dict[str, Any] = {"name": name, "kind": value_kind(values.get(name)), + "declared": field_type(field) if field else None, + "slot": by_field.get(name)} + bound.append(item) + payload = {k: values.get(k) for k in names} + out: dict[str, Any] = { + "adapter": ADAPTER, + "binding": "values_in_statement", + "template_hash": _hash(template), + "inputs_hash": _hash(json.dumps(payload, ensure_ascii=False, sort_keys=True, default=str)), + "declared": contract(declared_fields.values()), + "parameters": bound, + } + if with_template: + out["template"] = template + if source: + out["source"] = dict(source) + return out + + +def plan(template: str, *, fields: Iterable[Mapping[str, Any]], values: Mapping[str, Any], + source: Mapping[str, Any] | None = None, node_id: str | None = None, + where: str = "入口字段") -> Statement: + """「现在就发一条 SQL」的入口用:先按声明的字段把这次的值定下来(resolve:显式非空值优先、否则声明缺省值), + 再判参数完整性,过了才渲染成字面语句,附快照材料——检查、渲染、材料里的输入哈希用的是**同一份 resolved values**。 + + 不合规抛 ParameterRefused(缺参数、未声明、认不出的写法、值承载不了),调用方据此回 4xx,别发 SQL。 + + values 按同一套存在性语义收(None 与空串都算没给):没过滤就传进来的调用方,等于把「显式空串」当值渲染出去—— + resolve 会先把它按「没给」处理(有声明缺省值就用缺省值,没有就判缺参数)。已经自己补过缺省值的入口传进来的是 + 补好的 values,结果不变。 + + 注意:现在**没有正式入口调它**(试跑、组合式问数、派生图、正式出具各走自己的入口,都在发起/派生之前用 + check_nodes / check_template 判过)——它是给下一个入口(QueryCore 的固定执行)准备的共享层接口,行为由测试锁住。""" + declared_fields = declared(fields) + resolved = resolve(declared_fields.values(), values) + problems = check_template(template, fields=declared_fields, values=resolved, node_id=node_id, where=where) + if problems: + raise ParameterRefused(problems) + return Statement(statement=render(template, resolved), + material=material(template, values=resolved, declared_fields=declared_fields, source=source)) + + +# ========================================================================== +# 节点的参数契约(组合式问数、对账图写,运行时认) +# ========================================================================== + + +def marker(*, rendered: Any, template: str | None = None, values: Mapping[str, Any] | None = None, + declared_fields: Iterable[Mapping[str, Any]] = (), source: Mapping[str, Any] | None = None) -> dict[str, Any]: + """写进节点 data.config[KEY] 的参数契约:**rendered 那一项(tool 的 args / merge 的 sql)已经是渲染好的字面语句**, + 运行时的模板渲染一概不碰它——不然值里的 `{{ }}` 会被再解释一遍(K01 的二次渲染反例)。 + + rendered 必给:契约按它的哈希与节点上那一项绑定,节点被复制、被改过之后契约自动作废(见 literal_keys)。写契约的人 + 必须把它要注解的那份内容原样交进来(和写进节点的必须是同一个对象)。 + + template/values 给了就再把材料写上(源模板哈希、规范化输入哈希、参数契约、每个参数写在哪儿、出处);**不写源模板 + 正文**:engine/variables 会把节点配置里每一段带 {{ }} 的字都当活引用扫,正文留在节点上会把取数模板的占位符报成 + 「没有任何节点产出」,那张图就跑不起来了。""" + out: dict[str, Any] = {"mode": LITERAL_ARGS, "adapter": ADAPTER, HASH_KEY: rendered_hash(rendered)} + if template is not None: + out.update(material(template, values=values or {}, declared_fields=declared(declared_fields), + source=source, with_template=False)) + elif source: + out["source"] = dict(source) + return out + + +def contract(fields: Iterable[Mapping[str, Any]]) -> list[dict[str, Any]]: + """参数契约:入口字段按声明顺序写成 {name, type, required, default}(快照与审核看得懂的那一份)。""" + out: list[dict[str, Any]] = [] + for field in declared(fields).values(): + out.append({"name": field["name"], "type": field_type(field), "required": bool(field.get("required")), + **({"default": field["default"]} if field.get("default") is not None else {})}) + return out + + +def mode_of(config: Mapping[str, Any] | None) -> str | None: + """契约里写的模式(data.config[KEY])。**只看写了什么,不核对哈希**——判断要不要跳过渲染、要不要跳过画布校验, + 一律用 literal_keys / is_literal;这个只用来断言「服务端写下了契约」。""" + marker_ = (config or {}).get(KEY) + mode = marker_.get("mode") if isinstance(marker_, Mapping) else None + return LITERAL_ARGS if mode == LITERAL_ARGS else None + + +def rendered_hash(value: Any) -> str: + """契约注解的那一项(tool 的 args / merge 的 sql)的确定哈希。字典按键排序(canonical_json),字符串按原文。""" + from app.core.artifact_store import canonical_json + + return _hash(value if isinstance(value, str) else canonical_json(value)) + + +def literal_keys(config: Mapping[str, Any] | None, node_type: str | None) -> tuple[str, ...]: + """这个节点上「服务端渲染好的字面语句」在哪个键上(tool 的 args / merge 的 sql)——**核对过哈希**才算,其余为空。 + + 契约是服务端写在节点上的,但节点会被复制、会被改:改过 args / sql 之后,契约说的已经不是这一条语句了。只有契约里的 + rendered_hash 与当前那一项对得上,才按 literal 处理(跳过渲染、跳过模板扫描、快照用契约里的材料);对不上(复制后 + 改了、改回普通模板、改了别的参数)一律当没写契约——正常渲染、正常判参数,画布的变量校验也照常扫。""" + keys = LITERAL_KEY.get(str(node_type or "")) + if not keys or mode_of(config) != LITERAL_ARGS: + return () + marker_ = (config or {}).get(KEY) + if not isinstance(marker_, Mapping): + return () + if marker_.get(HASH_KEY) != rendered_hash((config or {}).get(keys)): + return () + return (keys,) + + +def is_literal(config: Mapping[str, Any] | None, node_type: str | None) -> bool: + """这个节点的 args / sql 是不是「服务端渲染好的字面语句,而且没被改过」:是就跳过渲染、跳过模板扫描。""" + return bool(literal_keys(config, node_type)) + + +def marker_material(config: Mapping[str, Any] | None, node_type: str | None) -> dict[str, Any] | None: + """契约里要进查询快照的部分(去掉 mode 与 rendered_hash):源模板哈希、规范化输入哈希、参数契约、参数类型与写在哪儿、 + 出处。**只有核对过哈希才给**——过时的契约说的不是这一条语句,拿它当证据就是失真。""" + if not is_literal(config, node_type): + return None + marker_ = (config or {}).get(KEY) + return {k: v for k, v in marker_.items() if k not in ("mode", HASH_KEY)} + + +def contract_of(config: Mapping[str, Any] | None) -> list[dict[str, Any]]: + """节点上那份参数契约声明的参数(name / type / required / default),原样的一份。没写契约的空数组。""" + marker_ = (config or {}).get(KEY) + items = marker_.get("declared") if isinstance(marker_, Mapping) else None + return [dict(d) for d in items or [] if isinstance(d, Mapping) and d.get("name")] + + +__all__ = ["ADAPTER", "CODES", "CONTEXTS", "FILTERS", "HASH_KEY", "KEY", "LITERAL", "LITERAL_ARGS", "LITERAL_KEY", + "MISSING", "ParameterRefused", "Problem", "SNAPSHOT_KEY", "Slot", "Statement", "UNDECLARED", "UNSUPPORTED", + "check_nodes", "check_template", "contract", "contract_of", "declared", "describe", "dynamic_input_writings", + "field_type", "input_refs", "is_literal", "literal_keys", "literal_problem", "marker", "marker_material", + "material", "mentions_input", "mode_of", "plan", "provided", "render", "rendered_hash", "resolve", + "runtime_problems", "slots_of", "value_kind"] diff --git a/backend/app/ledger/querycore.py b/backend/app/ledger/querycore.py new file mode 100644 index 00000000..bbd664f3 --- /dev/null +++ b/backend/app/ledger/querycore.py @@ -0,0 +1,1721 @@ +"""进程内 QueryCore 固定执行(K09):按一份**已发布的固定口径**跑一次,交回类型化标量与证据引用。 + +这一层是「按固定计划执行」的服务,不是又一个入口平台。一次调用只说五件事:口径身份(workflow + card,版本可点名、 +不点名就读**推荐版并当场固定**)、要算哪几个指标(K08 闭包)、这次入口参数的**类型化取值**、预算与 trace。回来的是 +一份结果:类型化 metrics、这次实际用到的发布/manifest 引用(K07)、selection/closure 身份、参数解释与哈希(K01)、 +数据时点与质量状态、每条查询的执行/attempt/工件/来源证据引用,以及「这次到底算成了没有」。 + +**这一版只按显式选择执行。** `metric_ids` 必须点名(空的选择直接拒,不静默当整卡);交回的是标量值(声明成表的指标 +在发 SQL 之前就拒)。「整卡」与表形输出留给以后的版本,不在这里按缺省猜。 + +**固定的是发布物,不是当下这张图。** 执行的是不可变版本行里的那一版图(K07 的发布清单就是按它物化的),清单必须读得 +出来、且**就是这一版这一张图**的(图指纹对得上、图上的源头口径卡一张不缺);清单里记着的编译器/绑定/参数/解析器约定 +和现在这一套不兼容就**明确拒绝**,绝不按新编译器现场重解释旧发布(A09)。没有发布清单的老资产(legacy)照样拒:旧 trial +路径一个字不动,但不能拿它冒充 QueryCore 的固定发布执行。 + +**执行路径零模型、零编译。** 内部 LLM = 0(派生的探针图里只有入口、取数、口径卡、出口,没有报告/Agent 节点), +作者侧 SQL 编译 = 0(只按固定计划做参数绑定与选择展开:K01 的 `params.plan` 把这一版模板按这次的值渲染成字面语句, +K08 的闭包决定执行哪几条查询、要哪些参数)。不建通用 Agent、不建任务平台、不注册驱动、不做结果缓存。 + +**进程内、可超时。** `run_manager.start` 起一次探索运行(`READ_ONLY_OPTION` 只读边界),随后在**同一个事件循环里** +`await` 它收尾(`run_manager.wait_idle`:等任务,不阻塞循环)。到点还没收尾就照实交回 `status="running"` + run_id, +**绝不把超时说得像成功**;空指标、部分查询没结果、某个指标被遮罩也一样 `ok=False`。 + +**身份与用途由宿主定,客户端改不了。** 认证主体来自服务端身份(HTTP 入口从 `current_principal()` 取,宿主入口由调用方 +显式传),purpose 是**宿主常量**:默认交互入口是 `compose`(探索运行,走 K07 的同一套判定但不继承正式身份,也不拿它绕过 +formal);给 K10 父 Run 用的是 `execute_formal`(purpose=formal,复用同一个 `publications.judge`,发布依据不齐就拒)。 +客户端没有传 purpose / role 的路子——两个入口都不收这两个字段。 + +**普通使用者按资产授权(K14)。** **每一个用途**(compose 的普通问数、交互入口、画布试跑、父 Run 的 compose 调用,以及 formal +的 `execute_formal` 与正式父 Run 派生的那一次执行)在**固定 workflow + version 之后、起 Run 之前**都多判一道:这一版口径有没有 +授权给这次的 actor(`apps/access.caliber_role`,靠的是 AppGrant 加上应用当前发布版 `AppVersion.pins` 精确固定着这一版), +到 `use` 及以上才放行,否则当场 403(`querycore_not_authorized`)——HTTP 入口、固定请求路由、自动路由、`caliber_query` 工具 +这几条路都靠它兜底,谁也不能靠「换一个入口」绕过去;应用图里引用一份没授权给它的口径同样在这次执行被拒。**正式还要多一道**: +formal 在授权之后照旧走 `publications.judge`(发布依据不齐照样拒),两道都过才执行。builder / admin / 关登录由**调用方**显式 +放行(`auth/chat_policy.restricted_actor`),这几档不写进资产授权函数;actor 缺失(认不出是谁)按普通使用者算:资产授权查不到 +主体就是没有授权,照拒。 + +**服务端替普通使用者准备的那条路(`execute_prepared`)。** 普通使用者的模型生成的图里**不要求**它自己画口径查询:服务端 +在准备一轮问数据时把 `caliber_query` 自动绑进它的 Agent / 调用工具节点(chat/launch,只给有授权口径的主体绑),模型因此 +能自己挑一份有授权的口径调用。要一条**deterministic** 的固定执行(一条确定请求直达、不经模型)时用 `execute_prepared`: +服务端按固定的 workflow / version / card / metric_ids / inputs 搭一张最小的**父图**(入口 → 调用工具 caliber_query → 出口), +经 `user_chat_run` 那套白名单与选项(遮罩 + 只读)起一次探索父 Run,**实际执行走的是 `caliber_query` 工具**(派生的子运行 +就是 `execute` 那一次固定执行),当场 await 收尾,交回与 `execute` 同形的 Outcome:run_id 是这次调用起的父 Run +(普通使用者读得到它:显式绑定、白名单、遮罩/只读、每条 query artifact 接回的证据都在它上面),execution_run_id 是它派生 +出来真正跑那几条 SQL 的子运行。用户不编辑图,执行层却有明确的绑定、白名单与父 Run 证据。 + +**K10:父 Run 的工具入口(`caliber_query`)。** 一次运行里的 Agent / 调用工具节点绑上这个工具,就按一份固定口径把数取回来: +工具用的是**父 Run 的上下文**——父 Run 的用途决定这次走 formal 还是 compose(正式父 Run 用 formal judge;交互、画布这类 +compose 父 Run 拿不到正式身份),父 Run 固定的上传/记录源版本、运行选项(遮罩、只读、数据目录视图)与来源照原样带下去。 +执行仍然是 K09 的进程内固定执行:派生出来的探针运行是**明确的子 Run**(origin 里记着 `parent_run_id`,来源也带下去, +不失去父关系),并且**当场 await 到收尾**。回来的是与交互工作台同一种形状的结果:metrics + queries 数组,每条查询都带 +query_id / execution_id / attempt 与工件、来源、参数材料;父 Run 的节点据此把每条 query artifact 以合法引用接回自己的封存 +证据(伪造的、别的运行落的、不是 query_snapshot 的工件一律拒绝,见 capabilities.registry.snapshot_owned)。 + +**值只被模板替换一次、且不无条件转 float。** 每个参数的解释与哈希来自 `params.plan` 的同一份 resolved 值(检查、渲染、 +快照材料共一份);实际执行过的语句与它不一致(运行期被重新绑定)照实报 `querycore_rebound`。交回的值原样保留类型: +JSON 里的整数就是精确整数(大整数不转 float),十进制文本原样保留(记成 `decimal`),布尔/字符串/空值各按各的。 + +**交回的是证据引用,不是 SQL 正文。** 每条查询给工件 id、来源(workflow/version/node)、attempt(那次执行的执行号)、 +调用 id、列与行数、是否截断、以及**这次计划的语句哈希/参数输入哈希与执行时那份的哈希**——两串哈希对得上就说明这次没有 +运行期重绑定。口径的 SQL 正文(连同快照里记着的源模板)不外发:里面可能写着遮罩值,要读正文走证据接口(那里按遮罩处理)。 + +**K13:量这一层自己。** 交回的 `measurement` 记这一次的分段耗时(发布/定位、闭包/计划、参数、排队、数据库、证据、总耗时)、 +计数(计划与真发出去的 SQL 条数、内部模型调用数、交回的查询条数与被截断的条数、问题/错误/超时)与身份(trace / run / +query ids)。测量只读时钟与这次运行自己留下的记录与封存事件,不改执行路径:不加缓存、不改计划、不重试。**量不到的一律 +是 None**——没跑完(超时)就没有执行证据,数据库那一截与 SQL 条数不填 0 冒充;排队那一项来自运行记录的 `usage.queue_ms` +(引擎在等并发名额前后量的那一段),不是等人审批的 `wait_ms`,老运行没有这一项就是 None。 +""" +from __future__ import annotations + +import asyncio +import json +import logging +import re +import time +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field +from decimal import Decimal +from typing import Any + +from pydantic import BaseModel, Field +from sqlalchemy.ext.asyncio import AsyncSession + +from app.apps import publications +from app.tools.registry import ToolContext, execution_id_of, register + +logger = logging.getLogger(__name__) + +#: 默认交互入口的用途(探索/组合式问数那一档):不是正式身份,也不因为缺验证审阅被拦 +DEFAULT_PURPOSE = publications.PURPOSE_COMPOSE +#: 宿主给 K10 父 Run 用的用途:和正式运行同一套发布依据判定(复用 publications.judge) +HOST_PURPOSE = publications.PURPOSE_FORMAL + +#: K10 注册进工具登记表的**真实工具名**(不是 `db_query__` 前缀那类动态工具):父 Run 的 Agent / 调用工具节点绑它, +#: 就按一份固定口径取一次数(app/ledger/querycore.execute),并把每条 query artifact 接回父 Run 的证据。 +CALIBER_QUERY = "caliber_query" +#: 子 Run 的 origin 里记父运行 id 的键(capabilities.registry.snapshot_owned 按它认「明确派生的子运行」) +PARENT_RUN_KEY = "parent_run_id" +#: 运行选项(Run.options / RunContext.extra)里放这次口径查询预算的键:父 Run 发起时定下就照它,没定就走缺省 +BUDGET_OPTION = "caliber_query_budget" + + +def origin_kind() -> str: + """这次执行记在运行上的来源(engine/origin.QUERYCORE_ORIGIN):口径的固定执行,和口径试跑同一档探索运行。 + + 只从 engine/origin 的常量取,别处不许另写一个字符串。""" + from app.engine.origin import QUERYCORE_ORIGIN + + return QUERYCORE_ORIGIN + + +#: 一次执行默认最多等多久(秒)——到点交回 running,不冒充成功 +DEFAULT_TIMEOUT_S = 30.0 +#: 默认预算:这次最多执行几条查询(闭包里的查询数超过就拒,不静默少算) +DEFAULT_MAX_QUERIES = 32 + +# -------------------------------------------------------------------------- +# 机器码:拒绝时给程序认(值层面/执行层面的问题另见 problems 里的码) +# -------------------------------------------------------------------------- + +NOT_FOUND = "querycore_not_found" +CARD_MISSING = "querycore_card_missing" +VERSION_MISSING = "querycore_version_missing" +NOT_PUBLISHED = "querycore_version_unpublished" +MANIFEST_REQUIRED = "querycore_manifest_required" +MANIFEST_UNREADABLE = "querycore_manifest_unreadable" +INCOMPATIBLE = "querycore_incompatible" +SELECTION_REFUSED = "querycore_selection_refused" +INPUTS_REFUSED = "querycore_inputs_refused" +UNKNOWN_INPUT = "querycore_unknown_input" +PARAMETERS_REFUSED = "querycore_parameters_refused" +BUDGET_REFUSED = "querycore_budget_refused" +OUTPUT_UNSUPPORTED = "querycore_output_unsupported" +#: 工具入口(K10):不在任何运行里调用,就没有父运行可以把证据接回去 +NO_PARENT = "querycore_no_parent" +#: 普通使用者按这一版口径执行,但资产授权里没有给它(K14):起 Run 之前就拒 +NOT_AUTHORIZED = "querycore_not_authorized" +#: 父 Run 上已经固定的数据版本和这次要执行的口径对不上(另一份口径目标、源已经换了一版):明确拒,不静默换一版 +DATA_VERSION_CONFLICT = "querycore_data_version_conflict" +#: 准备好的那次执行(execute_prepared)里子运行跑的版本和这一层固定/授权的那一版对不上(推荐版在中途换过):照实说, +#: 不把另一版的数当这一版交出去 +VERSION_MOVED = "querycore_version_moved" +#: 上面这一批(起 Run 之前拒绝的那几个码):写给「普通使用者看到的失败说法只留码、不留口径身份」的地方按它们认 +#: (api/runs 的失败说法投影),别处不要另列一份 +REFUSAL_CODES = (NOT_FOUND, CARD_MISSING, VERSION_MISSING, NOT_PUBLISHED, MANIFEST_REQUIRED, MANIFEST_UNREADABLE, + INCOMPATIBLE, SELECTION_REFUSED, INPUTS_REFUSED, UNKNOWN_INPUT, PARAMETERS_REFUSED, BUDGET_REFUSED, + OUTPUT_UNSUPPORTED, NO_PARENT, NOT_AUTHORIZED, DATA_VERSION_CONFLICT, VERSION_MOVED) + +#: 结果里的问题码(ok=False 的原因) +NO_RUN = "querycore_run_missing" +EXECUTION = "querycore_execution" +TIMEOUT = "querycore_timeout" +EVIDENCE = "querycore_evidence" +EMPTY = "querycore_empty" +METRIC_MISSING = "querycore_metric_missing" +METRIC_NO_VALUE = "querycore_metric_no_value" +METRIC_MASKED = "querycore_metric_masked" +QUERY_MISSING = "querycore_query_missing" +REBOUND = "querycore_rebound" + +#: 运行到这几个状态就是终态了(interrupted 也算:它停在那儿不再自己往下跑);别的都是还在跑 +TERMINAL_RUN_STATUSES = ("succeeded", "failed", "cancelled", "interrupted") + +#: 十进制文本:带小数点/指数,或者位数多到 float 存不下(大整数不转 float,原样保留) +_DECIMAL_TEXT = re.compile(r"^[+-]?(?:\d+\.\d*|\.\d+|\d+(?:\.\d+)?[eE][+-]?\d+|\d{16,})$") +#: 取值本身就写成日期/时刻(含时区偏移):算「这次数据窗口」时按它认,认字段声明的类型之外再认一层值 +_DATE_LIKE = re.compile(r"^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?$") +#: 入口字段声明成时间类的:算「这次数据窗口」用 +_TIME_TYPES = ("date", "datetime", "time") + + +class QueryCoreRefused(Exception): + """这次固定执行不发起(服务层面就拒):message 给人看,code 给程序认,status_code 是 HTTP 入口该回的状态。 + + problems 是底层那一层原样的几条(参数完整性问题、闭包的未决项、发布依据的缺口……),带各自的机器码。""" + + def __init__(self, message: str, code: str, *, status_code: int = 409, + problems: Sequence[Any] = ()) -> None: + super().__init__(message) + self.message = message + self.code = code + self.status_code = status_code + self.problems = tuple(problems) + + def as_dict(self) -> dict[str, Any]: + return {"detail": self.message, "code": self.code, + **({"problems": [dict(p) for p in self.problems]} if self.problems else {})} + + +# -------------------------------------------------------------------------- +# 类型化取值:只认类型,不改值 +# -------------------------------------------------------------------------- + + +def typed(value: Any) -> str: + """这个值在 JSON 里的类型:integer / number / decimal / boolean / string / null / 别的类型名。 + + **不把 decimal 和大整数转成 float**(R06 的原值口径):JSON 里的整数已经是精确整数原样交回,十进制文本(驱动 + Decimal 落进工件后按文本存下来的)原样保留并标成 decimal,不四舍五入、不截位。""" + if value is None: + return "null" + if isinstance(value, bool): + return "boolean" + if isinstance(value, int): + return "integer" + if isinstance(value, float): + return "number" + if isinstance(value, Decimal): + return "decimal" + if isinstance(value, str): + return "decimal" if _DECIMAL_TEXT.match(value.strip()) else "string" + if isinstance(value, (list, tuple)): + return "array" + if isinstance(value, Mapping): + return "object" + return type(value).__name__ + + +def exact(value: Any) -> Any: + """值原样交回,只把 Decimal 换成它的十进制文本(精确位数一个不少)。 + + 接口这一层会把 Decimal 编码成 float(丢精度),所以十进制不能以 Decimal 的形状出这道门:换成文本、类型标成 + decimal。别的值(int / float / str / bool / None)原样,不做任何转换。""" + return str(value) if isinstance(value, Decimal) else value + + +def _typed_metric(metric: Mapping[str, Any], hidden: str | None) -> dict[str, Any]: + """一个指标的类型化投影:值原样保留(遮罩时不给值),带类型、单位、小数位与质量结论。""" + out: dict[str, Any] = {k: metric[k] for k in ("id", "name", "unit", "status", "rendered", "decimals", "format") + if metric.get(k) is not None} + if hidden: + out.update(masked=True, rendered=hidden, value=None, value_type="null", status="masked") + out["quality"] = {"status": "unknown", "checks": [ + {"code": "masked", "status": "unknown", "detail": "指标值已遮罩,不能在此作为结果交出"}]} + return out + value = metric.get("value") + out["value"] = exact(value) + out["value_type"] = typed(value) + out["quality"] = _metric_quality(metric) + return out + + +def _metric_quality(metric: Mapping[str, Any]) -> dict[str, Any]: + from app.engine.validation import metric_quality + + return metric_quality(dict(metric)) + + +# -------------------------------------------------------------------------- +# 预算 +# -------------------------------------------------------------------------- + + +def _budget_of(budget: Mapping[str, Any] | None) -> dict[str, Any]: + """这次执行的预算:最多几条查询、最多等多久。给了的照用,没给的用缺省(不新建一套额度体系)。""" + made = {"max_queries": DEFAULT_MAX_QUERIES, "timeout_s": DEFAULT_TIMEOUT_S} + for key in ("max_queries", "timeout_s"): + if budget and budget.get(key) is not None: + made[key] = budget[key] + return made + + +# -------------------------------------------------------------------------- +# 输入:类型化 +# -------------------------------------------------------------------------- + + +def _inputs_of(pinned: Any, inputs: Mapping[str, Any]) -> tuple[dict[str, Any], list[str]]: + """这次入口的取值:不认识的字段拒(不静默丢掉),按声明类型校验,再按 K01 的语义把缺省值补上。 + + 收值和试跑、组合式问数同一份(`params.provided`:显式传的空串算没给),校验用同一份表单(apps/forms), + 定值用同一份 `params.resolve`。 + + **这次选择用什么参数就是什么参数**:给了选择时,入口契约收窄成这次要用的那几个(K08 的 required_entry_fields)—— + 声明过、但这次不用的字段照收不误(不报「不认识」),**但不带进这次执行**,列表交回调用方记在 ignored 里, + 不悄悄用它跑出另一份数(B 独有那条查询的参数,选 A 时一律为 0)。""" + from app.apps.forms import input_schema, validate_form + from app.ledger import derive, params + + if not isinstance(inputs, Mapping): + raise QueryCoreRefused("入口参数要给一组字段和值", INPUTS_REFUSED, status_code=422) + narrowed = [dict(f) for f in pinned.entry_fields] + full = [dict(f) for f in derive.entry_fields(pinned.graph)] or narrowed + unknown = sorted(str(k) for k in inputs if str(k) not in params.declared(full)) + if unknown: + raise QueryCoreRefused(f"不认识的入口字段:{'、'.join(unknown)}", UNKNOWN_INPUT, status_code=422) + used = set(params.declared(narrowed)) + values = params.resolve(narrowed, params.provided({k: v for k, v in inputs.items() if str(k) in used})) + errors = validate_form(input_schema(narrowed), values) + if errors: + raise QueryCoreRefused(";".join(str(e.get("message")) for e in errors[:5]), INPUTS_REFUSED, + status_code=422, problems=[dict(e) for e in errors]) + return values, sorted(str(k) for k in inputs if str(k) not in used) + + +# -------------------------------------------------------------------------- +# 这次执行什么:K08 闭包 + K01 计划 +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class _Plan: + """一条查询的 K01 计划:渲染好的字面语句 + 快照材料(模板哈希、输入哈希、每个参数写在哪儿)。""" + + node_id: str + query_id: str + tool: str + statement: str + material: dict[str, Any] = field(default_factory=dict) + + def as_dict(self) -> dict[str, Any]: + from app.ledger import params + + return {"query_id": self.query_id, "node_id": self.node_id, "tool": self.tool, + "template_hash": self.material.get("template_hash"), + "statement_hash": params.rendered_hash(self.statement), + "inputs_hash": self.material.get("inputs_hash"), + "adapter": self.material.get("adapter"), + "parameters": [dict(p) for p in self.material.get("parameters") or []], + "declared": [dict(d) for d in self.material.get("declared") or []]} + + +def _sql_of(node: Mapping[str, Any]) -> str | None: + args = ((node.get("data") or {}).get("config") or {}).get("args") if isinstance(node, Mapping) else None + sql = args.get("sql") if isinstance(args, Mapping) else None + return sql if isinstance(sql, str) and sql.strip() else None + + +def _plans(pinned: Any, closure: Any, values: Mapping[str, Any]) -> tuple[list[_Plan], list[dict[str, Any]]]: + """这次要执行的每条查询的 K01 计划(闭包已经决定执行哪几条、要哪些参数)。 + + 检查、渲染、快照材料用的是同一份 resolved 值(params.plan);不合规(缺参数、未声明、值承载不了)在这里就把 + 逐条问题交回,**一条 SQL 都不发**。""" + from app.ledger import params + + by_node = {str(query.node_id): query for query in closure.queries} + plans: list[_Plan] = [] + problems: list[dict[str, Any]] = [] + for node in pinned.fetches: + node_id = str(node.get("id")) + sql = _sql_of(node) + if sql is None: + continue # 闭包已经拒过「取数节点没有可读 SQL」,这里不重判 + try: + statement = params.plan(sql, fields=pinned.entry_fields, values=values, + source={**pinned.ref(), "node_id": node_id}, node_id=node_id, + where=f"口径「{pinned.card_title}」的入口") + except params.ParameterRefused as e: + problems += [p.as_dict() for p in e.problems] + continue + query = by_node.get(node_id) + plans.append(_Plan(node_id=node_id, query_id=str(getattr(query, "query_id", "") or ""), + tool=str(getattr(query, "tool", "") or ""), statement=statement.statement, + material=dict(statement.material))) + return plans, problems + + +def _scalar_output(pinned: Any, metric_ids: Sequence[str]) -> None: + """首版只交标量:声明成 `contract.shape = table` 的指标在这里明确拒(不悄悄按第一行给个值)。""" + by_id = {str(m.get("id")): m for m in pinned.metrics} + for metric_id in metric_ids: + contract = (by_id.get(str(metric_id)) or {}).get("contract") + if isinstance(contract, Mapping) and str(contract.get("shape") or "scalar") != "scalar": + raise QueryCoreRefused( + f"指标「{metric_id}」声明成表(contract.shape={contract.get('shape')}):这一版只交标量结果", + OUTPUT_UNSUPPORTED, status_code=422) + + +# -------------------------------------------------------------------------- +# 证据:类型化指标 + 每条查询的执行引用 +# -------------------------------------------------------------------------- + + +async def _sealed_of(run_id: str, memo: dict[str, Any] | None) -> Any: + """这一次收尾的封存证据。给了 memo 就复用:`read_sealed` 每次都要把整条事件流重读一遍、重算一遍清单哈希 + (K13 量下来约 3.5ms),而一次收尾里指标、查询引用、执行量测三处读的是**同一份**已经封好的快照,没必要读三遍。 + 读不出来时照旧抛,由调用的那一处记一条自己的问题(语义不变)。""" + from app.engine.evidence_reader import read_sealed + + if memo is None: + return await read_sealed(run_id) + if "sealed" not in memo: + memo["sealed"] = await read_sealed(run_id) + return memo["sealed"] + + +async def _metrics_from(sealed_run_id: str, *, card_id: str, metric_ids: Sequence[str], + memo: dict[str, Any] | None = None, + ) -> tuple[list[dict[str, Any]], dict[str, Any]]: + """从封存证据里取这次要算的那几个指标,按闭包的顺序、**只认这张卡节点**(同一节点执行过多次取最后一次)。 + + 遮罩按试跑同一套(api/evidence 的 _Masks / _metric_masks):被遮的指标不给值,也照实标出来——数据源设了遮罩列 + 的时候,这里绝不能把值交出去。交回 (类型化指标, 原始指标),原始那一份给质量报告用。 + + memo 是这一次收尾里几处共用的封存证据(见 _sealed_of):给了就用那一份,没给就自己读一次。""" + from app.api.evidence import _Masks, _metric_masks + from app.engine.evidence_reader import metric_cards + + sealed = await _sealed_of(sealed_run_id, memo) + if not sealed.trusted: + return [], {"trusted": False} + masks = _Masks(sealed) + found: dict[str, dict[str, Any]] = {} + raw: dict[str, dict[str, Any]] = {} + for node_id, artifact, card in metric_cards(sealed): + if str(node_id) != str(card_id): + continue + for metric in card.get("metrics") or []: + if not isinstance(metric, dict) or not metric.get("id"): + continue + metric_id = str(metric["id"]) + if metric_id not in set(metric_ids): + continue + # 同一张卡执行过多次时按**最后一次**的产出算(和「节点最后一次产出」同一个认法), + # 不拿早先那次的值 + _, hidden = await _metric_masks(metric, node_id, artifact, sealed, masks, card=card) + found[metric_id] = _typed_metric(metric, hidden) + raw[metric_id] = dict(metric) + ordered = [found[mid] for mid in metric_ids if mid in found] + return ordered, {"trusted": True, "metrics": {mid: raw[mid] for mid in metric_ids if mid in raw}} + + +def _tables_of(sql: Any) -> list[str]: + from app.engine.evidence import sql_tables + + try: + return sql_tables(str(sql or "")) + except Exception: # noqa: BLE001 - SQL 读不出表名只影响这一条引用,不影响结果本身 + return [] + + +async def _queries_from(sealed_run_id: str, *, closure: Any, plans: Mapping[str, _Plan], + memo: dict[str, Any] | None = None) -> list[dict[str, Any]]: + """闭包里每条要执行的查询的执行引用:用了哪份快照工件、来源、attempt(exec)、列与行数、执行时的参数材料与哈希。 + + 每条查询按**逐次记下的执行**(sealed.query_records:一次执行一条,带 node_id / exec / execution_id)认它自己那一次, + 不按工件 id 去重的字典认:同一份内容会得到同一个工件 id(内容寻址),两条不同的逻辑查询(两个节点写同一条 SQL、 + 参数一样、数据一样)会落到**同一个**工件上,`sealed.queries` 那种字典只剩最后一条,早先那条就查不到自己了。 + + 同一个节点执行过多次时按**最后一次**算(同「节点最后一次产出」的认法)。读不出来/没有快照的照实留空,由调用方 + 记一条问题(不编造)。 + + memo 是这一次收尾里几处共用的封存证据(见 _sealed_of):给了就用那一份,没给就自己读一次。""" + from app.core.artifact_store import load + + sealed = await _sealed_of(sealed_run_id, memo) + out: list[dict[str, Any]] = [] + for query in closure.queries: + plan = plans.get(str(query.node_id)) + item: dict[str, Any] = {"query_id": query.query_id, "node_id": query.node_id, "tool": query.tool, + "source": dict(query.source), "metric_ids": list(query.metric_ids), + "computes_unselected": list(query.computes_unselected), + "required_entry_fields": list(query.required_entry_fields), + "sql_hash": query.sql_hash, "binding_fingerprint": query.binding_fingerprint, + "artifact": None, "attempt": None, "execution_id": None, "call_id": None, "via": None, + "columns": [], "row_count": None, "truncated": None, "column_types": {}, + "data_source": None, "data_version": None, "tables": [], "checks": [], + "schema_artifact": None, + "no_data": [], "parameters": None, "executed_sql": None, + "rebound": None, "found": False} + record = _query_record_of(sealed, str(query.node_id)) + if record is not None: + artifact = str(record.get("artifact") or "") + try: + snap = load(artifact) + except ValueError: + snap = None + if isinstance(snap, Mapping): + material = snap.get("parameters") if isinstance(snap.get("parameters"), Mapping) else None + item.update( + artifact=artifact, attempt=record.get("exec") if record.get("exec") is not None + else record.get("attempt"), + call_id=record.get("call_id"), via=record.get("via"), + # 这次实际执行的执行身份:同一次运行里同一条 SQL 跑两次(重跑、agent 两步)也各不相同, + # 按调用 id(agent)或这个节点第几次执行(run 内序列)区分(tools/registry.execution_ref) + execution_id=record.get("execution_id") or execution_id_of( + str(query.node_id), attempt=item.get("attempt"), call_id=record.get("call_id"), + run_id=sealed_run_id), + columns=[str(c) for c in snap.get("columns") or []], + row_count=len(snap.get("rows") or []), + truncated=bool(snap.get("truncated")), column_types=dict(snap.get("column_types") or {}), + data_source=record.get("source") or snap.get("source"), + data_version=snap.get("data_version"), tables=_tables_of(snap.get("sql")), + schema_artifact=snap.get("schema_artifact"), + checks=list(snap.get("checks") or []), no_data=list(snap.get("no_data") or []), + # 快照里的参数材料只留哈希与承载方式:源模板正文不外发(同试跑查询快照那一处) + parameters=({"inputs_hash": material.get("inputs_hash"), + "template_hash": material.get("template_hash"), + "adapter": material.get("adapter"), "binding": material.get("binding")} + if material else None), + executed_sql=snap.get("sql"), found=True) + if plan is not None: + # 运行期重绑定:实际执行的语句 / 它记下的参数材料必须和这次计划的一致(值只被模板替换一次)。要比对的是 + # 语句本身,所以它只活在这一层——**返回里不给 SQL 正文**(口径的 SQL 里可能写着遮罩值,同试跑查询快照 + # 那一处的分寸):交回的是两边的哈希与工件引用,要读正文走证据接口(那里按遮罩处理) + item["planned_statement_hash"] = plan.as_dict()["statement_hash"] + item["planned_inputs_hash"] = plan.material.get("inputs_hash") + item["rebound"] = _rebound(item, plan) + item.pop("executed_sql", None) + out.append(item) + return out + + +def _query_record_of(sealed: Any, node_id: str) -> dict[str, Any] | None: + """这个节点交回过的查询快照里**最后一次**的那一条(逐次身份,sealed.query_records)。 + + 按 node_id 从逐次记下的执行里取,不从按工件 id 去重的 `sealed.queries` 里取:两条不同的逻辑查询(两个节点写同一条 + SQL、参数一样、数据一样)会落到同一个工件上——那种字典只剩最后一条,早先那条就找不到自己那一次了。 + 老运行、只回了 tool.end 的执行(没有台账条目)逐次记录里没有,退回按工件去重的那一份,认法和以前一样。""" + records = [dict(r) for r in sealed.query_records_of(node_id) if r.get("artifact")] + if not records: + records = [{"artifact": str(artifact), **dict(info or {})} + for artifact, info in sealed.queries.items() + if str((info or {}).get("node_id") or "") == str(node_id)] + return records[-1] if records else None + + +def _rebound(item: Mapping[str, Any], plan: _Plan) -> str | None: + """这条查询执行时的语句/参数和计划对不上就是重绑定(返回一句原因,对上返回 None)。""" + if not item.get("found"): + return None + executed = item.get("executed_sql") + if isinstance(executed, str): + item["executed_hash"] = _statement_hash(executed) + if executed != plan.statement: + return "实际执行的语句和这次计划渲染出来的不一致(运行期被重新绑定)" + material = item.get("parameters") + if isinstance(material, Mapping) and material.get("inputs_hash") \ + and material.get("inputs_hash") != plan.material.get("inputs_hash"): + return "实际执行的参数输入哈希和这次计划的不一致(运行期被重新绑定)" + return None + + +def _statement_hash(statement: Any) -> str: + from app.ledger import params + + return params.rendered_hash(statement) + + +# -------------------------------------------------------------------------- +# 结果 +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class Outcome: + """一次固定执行的结果。`ok` 是「这次真的算成了」:执行成功、闭包里每条查询都有结果、点名的每个指标都有值(没被 + 遮罩)——空指标、部分结果一律 ok=False。 + + `run_id` 是**这次执行的那次运行**;`execute_prepared` 交回的 Outcome 里它是服务端起的父 Run(显式绑定、白名单、 + 遮罩/只读与证据都在它上面),真正跑那几条 SQL 的子运行写在 `execution_run_id`(派生的口径固定执行)——其余字段 + (status / metrics / queries / problems / quality)说的都是**子运行那一次**算成了没有。别的入口 execution_run_id 为空。""" + + run_id: str + status: str + ok: bool + workflow_id: str + card_id: str + version: int + explicit_version: bool + purpose: str + publication: dict[str, Any] + selection: dict[str, Any] + parameters: dict[str, Any] + metrics: tuple[dict[str, Any], ...] + queries: tuple[dict[str, Any], ...] + data: dict[str, Any] + quality: dict[str, Any] + problems: tuple[dict[str, Any], ...] + trace: Any = None + #: K13 的测量记录:这次执行量到的分段耗时与计数(见 Measurement)。量不到的字段是 None + measurement: Measurement | None = None + #: 这次调用派生出来真正执行的那次运行(execute_prepared 的子运行;别的入口为空) + execution_run_id: str | None = None + + def as_dict(self) -> dict[str, Any]: + return {"run_id": self.run_id, "status": self.status, "ok": self.ok, "workflow_id": self.workflow_id, + "card_id": self.card_id, "version": self.version, "explicit_version": self.explicit_version, + "purpose": self.purpose, "publication": dict(self.publication), + "selection": dict(self.selection), "parameters": dict(self.parameters), + "metrics": [dict(m) for m in self.metrics], "queries": [dict(q) for q in self.queries], + "data": dict(self.data), "quality": dict(self.quality), + "problems": [dict(p) for p in self.problems], + **({"trace": self.trace} if self.trace is not None else {}), + **({"execution_run_id": self.execution_run_id} if self.execution_run_id else {}), + **({"measurement": self.measurement.as_dict()} if self.measurement is not None else {})} + + +def _problem(code: str, message: str, **extra: Any) -> dict[str, Any]: + return {"code": code, "message": message, **{k: v for k, v in extra.items() if v not in (None, "")}} + + +# -------------------------------------------------------------------------- +# K13:一次固定执行的测量(分段耗时与计数) +# +# 量的是「这次固定执行自己」:发布/定位、闭包/计划、参数、排队、数据库、证据各花多久,发出去几条 SQL、调了几个 +# 模型、交回几条查询、有没有被截断、有没有出错或超时,以及 trace / run / query 的身份。测量只读时钟与这次运行自己 +# 留下的记录与封存事件,不改执行路径:不加缓存、不改计划、不重试。 +# -------------------------------------------------------------------------- + +#: 分段耗时的键(毫秒):locate/closure/params/run/evidence 首尾相接,加起来就是 total;queue 与 database 是 run 里面 +#: 的两段(各有出处,不是另加的时间);量不到的一律 None,不填 0 冒充 +PHASES = ("locate_ms", "closure_ms", "params_ms", "run_ms", "queue_ms", "database_ms", "evidence_ms", "total_ms") + + +class _Stage: + """分段计时:段与段首尾相接(`mark` 结束当前段、开下一段),total 从建它那一刻算起。只读时钟,不改执行。""" + + def __init__(self) -> None: + self._last = time.perf_counter() + self._started = self._last + self.ms: dict[str, int] = {} + + def mark(self, name: str) -> int: + now = time.perf_counter() + self.ms[name] = max(0, int((now - self._last) * 1000)) + self._last = now + return self.ms[name] + + def total_ms(self) -> int: + return max(0, int((time.perf_counter() - self._started) * 1000)) + + +@dataclass(frozen=True) +class Measurement: + """一次固定执行的测量记录(K13)。**只记这一次真的量到的**:没量到的一律 None,不填 0 冒充。 + + phases(毫秒): + + - `locate_ms` 发布/定位:版本解析(点名或推荐版)与固定、发布清单核验、用途判定; + - `closure_ms` 闭包/计划:K08 的显式选择展开、预算与输出形状判定; + - `params_ms` 参数:入口取值与校验(K01)、逐条查询的渲染与快照材料、探针图成形; + - `run_ms` 起运行到收尾:**含** queue 与 database 两段,也含图引擎自己的开销; + - `queue_ms` 排队:这次从要并发名额到拿到名额的时长(含发名额那一下的开销;没人在排队时就是那几毫秒),来自 + 运行记录的 `usage.queue_ms`(engine/runner 在要名额前后量的那一段),**不是**等人审批的 `wait_ms`;老运行、 + 还没收尾的运行没有这一项就是 None; + - `database_ms` 数据库:这次取数节点自己的 `node.finished.duration_ms` 之和(同一个节点执行多次取最后一次)。它 + 含着 SQL 往返、驱动与行映射,是这次执行里离数据库最近的一段,**不是**数据库内核时间; + - `evidence_ms` 证据:读封存证据、取指标与查询引用、拼结果与质量报告; + - `total_ms` 整次 `execute` 的墙钟。 + + counts:`planned_queries`(闭包里要执行的查询数)、`executed_sql`(真的发出去的 SQL 条数,按封存里逐次记下的查询 + 快照数,不是计划条数)、`llm_calls`(内部模型调用数,执行路径固定为 0)、`returned_queries` / `truncated_queries` + (交回证据引用的查询条数 / 其中被截断的条数)、`problems` / `errors`(结果里的问题条数,errors 不含超时)、 + `timeouts`(到点没收尾 = 1)。 + + ids:`run_id`、`trace`、`workflow_id` / `card_id` / `version`、`query_ids`、`execution_ids`——按其中任何一个都能把 + 这次测量定位回那条运行、那条查询。 + """ + + phases: dict[str, Any] + counts: dict[str, Any] + ids: dict[str, Any] + + def as_dict(self) -> dict[str, Any]: + return {"phases": dict(self.phases), "counts": dict(self.counts), "ids": dict(self.ids)} + + +def _queue_of(row: Any) -> int | None: + """这次排队等了多久(毫秒):运行记录上的 `usage.queue_ms`,由 runtime 在等并发名额前后量(engine/runner._drive)。 + + 没有这一项就是没量到(加这一项之前的运行、还没收尾的运行):返回 None,**绝不拿等人审批的 wait_ms 冒充排队**。""" + usage = getattr(row, "usage", None) + if not isinstance(usage, Mapping): + return None + queued = usage.get("queue_ms") + return int(queued) if isinstance(queued, int) and not isinstance(queued, bool) else None + + +def _from_evidence(sealed: Any, closure: Any) -> dict[str, Any]: + """封存事件里量得到的几样:取数节点各自的执行时长、真发出去几条 SQL、内部模型调用数。 + + 取数节点的执行时长按 `node.finished.duration_ms` 求和(同一个节点执行过多次取最后一次,同「节点最后一次产出」 + 的认法);SQL 条数按封存里**逐次**记下的查询快照数(同一份内容被两条查询执行两次就是两条),不是闭包里的计划 + 条数。模型调用数按 `llm.end` 事件数——执行路径 LLM=0,这一项是给「真的为 0」留个可核的数,不是估计。""" + fetch_nodes = {str(query.node_id) for query in closure.queries} + durations: dict[str, int] = {} + calls = 0 + for _, kind, node_id, data in sealed.events: + if kind == "llm.end": + calls += 1 + if kind != "node.finished" or not isinstance(data, Mapping) or str(node_id) not in fetch_nodes: + continue + spent = data.get("duration_ms") + if isinstance(spent, int) and not isinstance(spent, bool): + durations[str(node_id)] = max(0, spent) + return {"database_ms": sum(durations.values()), "llm_calls": calls, + "executed_sql": sum(1 for record in sealed.query_records + if str(record.get("node_id") or "") in fetch_nodes)} + + +def _measurement(stages: _Stage, *, run_id: str, workflow_id: str, card_id: str, version: int, closure: Any, + status: str, problems: Sequence[Mapping[str, Any]], queries: Sequence[Mapping[str, Any]], + facts: Mapping[str, Any], trace: Any) -> Measurement: + """把这次执行量到的收成一份记录。成功之后才读得到的(SQL 条数、数据库那一截、交回几条查询)没读到时是 None。""" + stages.mark("evidence_ms") + timeouts = sum(1 for problem in problems if str(problem.get("code")) == TIMEOUT) + # 证据读到了才算量到「执行了几条 SQL / 交回几条查询」:没跑完(超时)一条都没有,也不能按计划条数顶上 + measured = status == "succeeded" and facts.get("executed_sql") is not None + counts = { + "planned_queries": len(closure.queries), + "executed_sql": facts.get("executed_sql"), + "llm_calls": facts.get("llm_calls"), + "returned_queries": sum(1 for query in queries if query.get("found")) if measured else None, + "truncated_queries": (sum(1 for query in queries if query.get("found") and query.get("truncated")) + if measured else None), + "problems": len(problems), + "errors": len(problems) - timeouts, + "timeouts": timeouts, + } + phases = {name: stages.ms.get(name) for name in ("locate_ms", "closure_ms", "params_ms", "run_ms", "evidence_ms")} + # queue 与 database 是 run 里面的两段,各有各的出处:一个来自运行记录的排队那一项,一个来自封存事件里取数节点 + # 自己的执行时长;两样都不在阶段计时器里 + phases["queue_ms"] = facts.get("queue_ms") + phases["database_ms"] = facts.get("database_ms") + phases["total_ms"] = stages.total_ms() + assert set(phases) == set(PHASES), "分段耗时的键要和 PHASES 一致" + identity = { + "run_id": run_id, "trace": trace, "workflow_id": workflow_id, "card_id": card_id, "version": version, + "query_ids": [str(query.query_id) for query in closure.queries], + "execution_ids": [str(query["execution_id"]) for query in queries if query.get("execution_id")], + } + return Measurement(phases=phases, counts=counts, ids=identity) + + +# -------------------------------------------------------------------------- +# 固定执行 +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class _Prepared: + """一次固定执行在**起 Run 之前**已经判完、备好的东西(`_prepared` 交回)。""" + + workflow: Any + resolved: Any + #: 这一版的图(清单核验、口径要读的源都按它认) + graph: dict[str, Any] + #: K08 的固定闭包与它那一版的口径卡(`derive.load_pinned`) + loaded: Any + closure: Any + values: dict[str, Any] + ignored: list[str] + plans: dict[str, _Plan] + publication_ref: dict[str, Any] + #: 派生的探针图(真正跑的那张:入口、取数、口径卡、出口) + graph_spec: dict[str, Any] + + +async def _prepared(session: AsyncSession, *, workflow_id: str, card_id: str, metric_ids: Sequence[str], + inputs: Mapping[str, Any] | None, version: int | None, purpose: str, actor: Any, + budget: Mapping[str, Any] | None, timeout_s: float | None, + stages: _Stage) -> tuple[_Prepared, dict[str, Any]]: + """起运行之前判完这一次固定执行要用的东西:固定版本(并核普通使用者的资产授权)→ 核发布清单 → 解闭包 → 收参数。 + + `execute` 与 `execute_prepared` 共用这一份(两条路在起 Run 之前该判的一模一样,不各抄一遍):交回准备好的那一份 + 和这次的预算(`max_queries` / `timeout_s`,给了的照用)。""" + from app.apps.versions import is_published + from app.db.models import Workflow + from app.ledger import derive + + workflow_id, card_id = str(workflow_id or ""), str(card_id or "") + wanted = [str(m) for m in (metric_ids or []) if str(m or "").strip()] + if not wanted: + raise QueryCoreRefused("metric_ids 是空的:这次一个指标也不选(不静默当整卡)", SELECTION_REFUSED, + status_code=422) + attempted = _budget_of(budget) + if timeout_s is not None: + attempted["timeout_s"] = timeout_s + + # ---- 1) 版本:点名就固定到它;不点名读一次推荐版并固定(解析只发生这一次)---------------- + workflow = await session.get(Workflow, workflow_id) + if workflow is None: + raise QueryCoreRefused("工作流不存在,可能已被删除", NOT_FOUND, status_code=404) + resolved = await publications.resolve(session, workflow, version=version, purpose=purpose) + if resolved is None: + detail = (f"「{workflow.name}」没有 v{version} 这个版本" if version is not None + else f"「{workflow.name}」现在没有推荐版(还没发布过)") + raise QueryCoreRefused(detail, VERSION_MISSING, status_code=404) + if not is_published(resolved.row, current=workflow.published_version) or resolved.row.retired_at is not None: + raise QueryCoreRefused(f"「{workflow.name}」v{resolved.version} 没有发布或已退役,不能按固定口径执行", + NOT_PUBLISHED, status_code=409) + # 版本已经固定:普通使用者这一档先核资产授权,没授权就当场拒(一条 SQL 都不发,也不起 Run) + await _require_caliber(session, actor, purpose=purpose, workflow=workflow, version=resolved.version) + # 卡在不在图里(图不存在时也要给出具体的一句话)由后面的闭包解析说;这里先把「清单必须就是这一版这一张图」核掉 + + # ---- 2) K07:清单必须读得出来、就是这一版这一张图、约定与现在兼容(不现场重解释旧发布)----- + graph = (resolved.row.graph or {}) if isinstance(resolved.row.graph, dict) else {} + content = _verified_manifest(resolved, graph=graph) + publication_ref = await _judged(session, workflow, resolved, purpose=purpose, content=content, graph=graph) + stages.mark("locate_ms") + + # ---- 3) K08 闭包 + K01 参数语义(都在发起运行之前判完)-------------------------------- + try: + loaded = await derive.load_pinned(session, resolved.workflow_id, resolved.version, card_id, metric_ids=wanted) + except derive.NotDerivable as e: + # 卡不在/不是口径卡:这一版里根本没有这张卡,谁能补也不该在这里补 + code = CARD_MISSING if e.code in (derive.GONE, derive.NOT_CARD) else ( + SELECTION_REFUSED if e.code == derive.SELECTION else e.code) + raise QueryCoreRefused(e.message, code, status_code=409, + problems=[p.as_dict() for p in getattr(e, "problems", ())]) from None + if loaded.closure is None or loaded.closure.whole_card: + raise QueryCoreRefused("这次的点名没有解析成显式选择(闭包不完整)", SELECTION_REFUSED, status_code=409) + closure = loaded.closure + if len(closure.queries) > int(attempted["max_queries"]): + raise QueryCoreRefused( + f"这次要执行 {len(closure.queries)} 条查询,超过预算 {attempted['max_queries']}:不静默少算", + BUDGET_REFUSED, status_code=429) + _scalar_output(loaded, closure.metric_ids) + stages.mark("closure_ms") + # 入口取值与校验(K01)到逐条查询的渲染和探针图成形都算「参数」这一段 + values, ignored = _inputs_of(loaded, inputs or {}) + plans, parameter_problems = _plans(loaded, closure, values) + if parameter_problems: + first = parameter_problems[0] + raise QueryCoreRefused(f"参数完整性不通过:{first.get('message') or first.get('code')}", + str(first.get("code") or PARAMETERS_REFUSED), status_code=422, + problems=parameter_problems) + graph_spec = derive.caliber_probe(loaded).graph + stages.mark("params_ms") + return _Prepared(workflow=workflow, resolved=resolved, graph=graph, loaded=loaded, closure=closure, + values=values, ignored=ignored, plans={plan.node_id: plan for plan in plans}, + publication_ref=publication_ref, graph_spec=graph_spec), attempted + + +async def _require_caliber(session: AsyncSession, actor: Any, *, purpose: str, workflow: Any, version: Any) -> None: + """普通使用者按一份口径执行之前的那一道(K14):资产授权到 use 及以上才放行,否则 403(起 Run 之前就拒)。 + + - **每一个用途都过这一道**:compose(问数、交互入口、画布试跑、父 Run 的 compose 调用)与 formal(`execute_formal`、 + 正式父 Run 派生的那一次执行)一样——正式运行也不能替使用者执行一份没授权给它的口径。formal 另**额外**走 + `publications.judge`(发布依据不齐照样拒),两道都过才执行:授权这一道在前,依据那一道在后; + - 靠的是 `apps/access.caliber_role`:AppGrant(给本人、他所在的组、所有人,至少 use)加上应用**当前发布版**精确固定着 + 这一版(AppVersion.pins),两样都在才算「授权给了这个主体」; + - builder / admin / 关登录由**调用方**显式放行(`auth/chat_policy.restricted_actor`),这几档不写进资产授权函数; + - actor 缺失、认不出是谁:按普通使用者算——资产授权查不到主体就是没有授权,照拒(不拿「认不出」当放行)。""" + from app.apps.access import at_least, caliber_role + from app.auth.chat_policy import effective_actor, restricted_actor + + who = effective_actor(actor) + if not await restricted_actor(session, who): + return + version = int(version) + role = await caliber_role(session, who, str(workflow.id), version) + if at_least(role, "use"): + return + detail = "正式运行也一样要这一份授权。" if purpose != publications.PURPOSE_COMPOSE else "" + raise QueryCoreRefused( + f"没有权限:口径「{workflow.name}」v{version} 没有授权给你使用。" + detail + + "用一份已发布的口径要有应用授权(让搭建者把固定着这一版口径的应用授权给你,至少「使用」)," + "或者按数据源自己搭一张图", + NOT_AUTHORIZED, status_code=403, + problems=[{"code": NOT_AUTHORIZED, "workflow_id": str(workflow.id), "version": version, + "purpose": purpose, "role": role or ""}]) + + +async def execute( + session: AsyncSession, + *, + workflow_id: str, + card_id: str, + metric_ids: Sequence[str], + inputs: Mapping[str, Any] | None = None, + version: int | None = None, + purpose: str = DEFAULT_PURPOSE, + actor: str | None = None, + timeout_s: float | None = None, + budget: Mapping[str, Any] | None = None, + trace: Any = None, + parent_run_id: str | None = None, + run_options: Mapping[str, Any] | None = None, + data_versions: Mapping[str, Any] | None = None, + emit: Any = None, +) -> Outcome: + """按固定口径跑一次,交回类型化标量与证据引用。 + + - `workflow_id` + `card_id` 定口径身份;`version` 点名就固定到它,不点名就**读一次推荐版并固定**(不反复解析); + - `metric_ids` 是这次要算的指标(显式选择,走 K08 闭包;空的不当整卡); + - `inputs` 是这次入口的类型化取值(不认识的字段拒,缺参数在发 SQL 之前拒); + - `purpose` 由**宿主常量**定(默认 `compose`;`execute_formal` 传 formal),客户端传不了; + - `actor` 是认证主体(HTTP 入口从服务端身份取,宿主入口显式传),只记进运行来源,不从请求体读;普通使用者执行时 + (compose 与 formal 一样)**固定版本之后、起 Run 之前**还要核这一版口径的资产授权(`apps/access.caliber_role` 到 + use 及以上,否则 403 `querycore_not_authorized`,见 `_require_caliber`); + - `budget` 给 `max_queries` / `timeout_s`,`trace` 原样记进运行来源; + - `parent_run_id` / `run_options` / `data_versions` / `emit` 是 K10 父 Run 交下来的上下文:派生出来的探针运行是 + **明确的子运行**(origin 里记 parent_run_id),照原样带上父 Run 的选项与固定的数据版本(遮罩、只读、上传/记录源 + 版本固定一条不断);这次口径那一版要读、父 Run 发起时又没算到的源,在这一层按**父 Run 的**类别与主体补固定 + (`pin_sources_for_parent`),`emit` 用来把这次补固定追加进父 Run 的事件流。 + + 拒(不发起)抛 QueryCoreRefused;发起了就交回 Outcome(含没跑完的 `status="running"`)。**被拒的这一次没有运行,也就 + 没有测量记录**(那时一条 SQL 都没发,没有运行可以定位)。""" + from app.auth.chat_policy import actor_name, effective_actor + + # K13:这次执行的分段计时从进这门就开始 + stages = _Stage() + if purpose not in publications.PURPOSES: + raise ValueError(f"不认识的用途:{purpose}") + # 认证主体:判授权用它本身(给了的用它,没给就取当前请求的身份——HTTP 入口在中间件里写好了),角色与组不丢; + # 记进运行、算行级范围用它的**名字**。两处是同一个主体,不能一处认得出、另一处认不出 + subject = effective_actor(actor) + name = actor_name(actor) + prepared, attempted = await _prepared(session, workflow_id=workflow_id, card_id=card_id, metric_ids=metric_ids, + inputs=inputs, version=version, purpose=purpose, actor=subject, + budget=budget, timeout_s=timeout_s, stages=stages) + resolved, workflow = prepared.resolved, prepared.workflow + loaded, closure = prepared.loaded, prepared.closure + + # ---- 4) 父 Run 上补固定这次要读的源(K10:晚解析的源固定在父 Run 上,不留给子运行)-------- + # 子运行里补(tools/datasource._pin_late_records)会按 exploratory 重算行级范围(正式父 Run 的 all 被收成 + # mine/none)、而且只写子运行那一行:同一次运行里的两次调用各固定各的版本。这里按父 Run 的类别与主体固定, + # 记在父 Run 上,子运行照它继承。 + versions = data_versions + if parent_run_id: + versions = await pin_sources_for_parent(parent_run_id=str(parent_run_id), resolved=resolved, + graph=prepared.graph, card_id=str(loaded.node_id), + versions=data_versions, emit=emit) + + # ---- 5) 起一次只读的探索运行(进程内 await,超时交回 running)-------------------------- + run = await _start(prepared.graph_spec, values=prepared.values, workflow=workflow, resolved=resolved, + closure=closure, publication_ref=prepared.publication_ref, purpose=purpose, actor=name, + trace=trace, parent_run_id=parent_run_id, run_options=run_options, + data_versions=versions) + status = await _await_run(run.id, timeout_s=float(attempted["timeout_s"])) + stages.mark("run_ms") + + # ---- 6) 结果:类型化指标 + 证据引用 + 质量 -------------------------------------------- + return await _outcome(run.id, status=status, workflow=workflow, resolved=resolved, loaded=loaded, closure=closure, + plans=prepared.plans, values=prepared.values, ignored=prepared.ignored, + publication_ref=prepared.publication_ref, purpose=purpose, attempted=attempted, + trace=trace, stages=stages) + + +async def execute_formal( + session: AsyncSession, + *, + workflow_id: str, + card_id: str, + metric_ids: Sequence[str], + inputs: Mapping[str, Any] | None = None, + version: int | None = None, + actor: str | None = None, + timeout_s: float | None = None, + budget: Mapping[str, Any] | None = None, + trace: Any = None, + parent_run_id: str | None = None, + run_options: Mapping[str, Any] | None = None, + data_versions: Mapping[str, Any] | None = None, + emit: Any = None, +) -> Outcome: + """宿主入口(K10 父 Run 用):purpose 固定成 formal,走**同一个** `publications.judge`——发布依据不齐(缺记录、 + 不是 matched、没有认证审阅、只确认了一部分、清单不是这一版这一张图的、老资产没有清单)一律拒,不换路、不降级。 + + 这一层不发起正式运行(正式身份由父 Run 持有):它只按 formal 的分寸要求同一份依据,执行本身仍是进程内的固定执行。 + **资产授权那一道照样要过**(`_require_caliber`,对每个用途都判):普通使用者拿不到这一版口径的 use 及以上时,正式运行也 + 不能替它执行——先是授权、再是发布依据,两道都过才跑。父 Run 交下来的上下文 + (parent_run_id / run_options / data_versions / emit)同 `execute`,原样带进派生的子运行,晚解析的源也照 `execute` 那一套 + 固定在父 Run 上(行级范围取正式这一档:看全部)。""" + return await execute(session, workflow_id=workflow_id, card_id=card_id, metric_ids=metric_ids, inputs=inputs, + version=version, purpose=HOST_PURPOSE, actor=actor, timeout_s=timeout_s, budget=budget, + trace=trace, parent_run_id=parent_run_id, run_options=run_options, + data_versions=data_versions, emit=emit) + + +# -------------------------------------------------------------------------- +# 服务端替普通使用者准备的那一条(K14):最小父图 + 真的从 caliber_query 工具走一次 +# -------------------------------------------------------------------------- + +#: `execute_prepared` 那张最小父图的节点 id:入口、调用工具(口径查询)、出口 +PREPARED_INPUT = "start" +PREPARED_NODE = "caliber" +PREPARED_OUTPUT = "out" + + +def prepared_graph(workflow_id: str, *, card_id: str, metric_ids: Sequence[str], + inputs: Mapping[str, Any] | None = None) -> dict[str, Any]: + """服务端替普通使用者搭的那张**最小父图**:入口 → 调用工具(`caliber_query`)→ 出口。 + + **显式绑定**,不是模型挑的:口径身份(workflow + card)、要算的指标、这次入口取值都写死在节点上,用户不碰画布。这三个 + 节点都在 user_chat_run 那一份白名单里(input / tool / output),跑起来照样带遮罩与只读;能碰哪些口径仍由 QueryCore 按 + 资产授权核(`_require_caliber`,工具里那一次执行再核一遍)。""" + def node(nid: str, ntype: str, label: str, config: dict[str, Any]) -> dict[str, Any]: + return {"id": nid, "type": ntype, "position": {"x": 0, "y": 0}, + "data": {"label": label, "config": config}} + + args: dict[str, Any] = {"workflow": str(workflow_id), "card": str(card_id), + "metric_ids": [str(m) for m in metric_ids], "inputs": dict(inputs or {})} + return { + "nodes": [node(PREPARED_INPUT, "input", "入口", {}), + node(PREPARED_NODE, "tool", "按口径取数", {"tool": CALIBER_QUERY, "args": args}), + node(PREPARED_OUTPUT, "output", "成果", + {"fields": [{"name": "口径", "value": f"{{{{ nodes.{PREPARED_NODE}.ok }}}}"}]})], + "edges": [{"source": PREPARED_INPUT, "target": PREPARED_NODE}, + {"source": PREPARED_NODE, "target": PREPARED_OUTPUT}], + } + + +async def execute_prepared( + session: AsyncSession, + *, + workflow_id: str, + card_id: str, + metric_ids: Sequence[str], + inputs: Mapping[str, Any] | None = None, + version: int | None = None, + actor: Any = None, + timeout_s: float | None = None, + budget: Mapping[str, Any] | None = None, + trace: Any = None, + origin_kind: str = "chat", + origin: Mapping[str, Any] | None = None, + run_options: Mapping[str, Any] | None = None, +) -> Outcome: + """普通使用者的一条**确定请求**:服务端替它搭最小父图、经 `user_chat_run` 起一次探索父 Run,实际从 `caliber_query` 工具走。 + + 与 `execute` 的区别只有一件:那条路是服务端自己起一次探针运行(用户看不到图),这一条是**真的发一次父 Run**——图里有 + 一个显式绑定 `caliber_query` 的调用工具节点,执行的是同一个工具(同一份固定执行、同一个子运行),证据接在父 Run 上。 + 普通使用者的「模型自己挑口径」那条路是它在自己的图里绑这个工具(chat/launch 自动绑定);这一条用于确定请求直达,不经模型。 + + - 起 Run 之前判的东西和 `execute` **一模一样**(`_prepared` 同一份):固定版本、普通使用者的资产授权 + (`querycore_not_authorized`)、发布清单、K08 闭包、K01 参数——没授权/读不出来/点错了都在起任何 Run 之前拒; + - 父 Run 选项照普通问数:遮罩(MASK_RESULTS_OPTION)+ 只读(READ_ONLY_OPTION),记忆范围是这位使用者自己的;这次口径 + 查询的预算写进父 Run 的选项(`BUDGET_OPTION`),派生的子运行照它走;`origin_kind` / `origin` 由调用方给(问数据那一轮 + 是 chat + 对话/轮次),普通使用者读得到这次运行(origin_kind=chat、遮罩、自己是发起人); + - 交回的 Outcome 与 `execute` 同形:`run_id` 是这次起的**父 Run**(显式绑定、白名单、遮罩/只读与每条 query artifact + 的证据都在它上面),`execution_run_id` 是它派生出来真正跑那几条 SQL 的子运行;metrics / queries / problems / + quality / status / ok 说的都是子运行那一次算成了没有; + - 父 Run 没跑成(工具被拒、运行失败、到点没收尾):照实交回 ok=False + 一条问题(`status="running"` 时报超时), + **绝不把「没跑成」说成成功**;这时没有子运行可定位,也就没有 metrics。 + - `version` 点名时按**点名的那一版**固定并授权这一道;工具那条路固定的是**推荐版**(`caliber_query` 的参数里没有版本, + 读一次推荐版并当场固定)——两者对不上(推荐版在这中间换过)时照实记一条 `querycore_version_moved` 并交回 ok=False, + 不把另一版的数当这一版交出去。 + + 拒(没发起任何运行)抛 QueryCoreRefused;发起了就交回 Outcome。""" + from app.auth.chat_policy import actor_name, effective_actor + from app.chat.launch import user_chat_run + from app.engine.launch import LaunchRefused, launch_run + + stages = _Stage() + # 判授权用主体本身(角色与组不丢),记进运行、当记忆范围用名字:和 execute 同一套 + subject = effective_actor(actor) + name = actor_name(actor) + prepared, attempted = await _prepared(session, workflow_id=workflow_id, card_id=card_id, metric_ids=metric_ids, + inputs=inputs, version=version, purpose=DEFAULT_PURPOSE, actor=subject, + budget=budget, timeout_s=timeout_s, stages=stages) + # 图上的口径身份用**这一层固定下来的**那一份(卡节点是核对过的源头卡,指标是闭包收窄过的那几个) + graph = prepared_graph(prepared.resolved.workflow_id, card_id=str(prepared.loaded.node_id), + metric_ids=list(prepared.closure.metric_ids), inputs=inputs or {}) + # 白名单、记忆范围、遮罩与只读:和 HTTP 发起一轮问数据共用同一份(chat/launch),不在这里另抄一条 + memory_scope, chat_options, graph = await user_chat_run(session, graph, name) + options = {BUDGET_OPTION: dict(attempted), **dict(run_options or {}), **chat_options} + try: + parent = await launch_run(session, graph=graph, input_payload={}, memory_scope=memory_scope, + run_class="exploratory", actor=name, options=options, origin_kind=origin_kind, + origin=dict(origin) if origin is not None else None) + except LaunchRefused as e: + # 没发起任何运行:和服务层别的拒绝同一个形状(调用方只认 QueryCoreRefused 这一种) + raise QueryCoreRefused(e.message, EXECUTION, status_code=e.status_code) from None + status = await _await_run(parent.id, timeout_s=float(attempted["timeout_s"])) + stages.mark("run_ms") + return await _prepared_outcome(parent.id, status=status, prepared=prepared, attempted=attempted, trace=trace) + + +async def _prepared_outcome(parent_run_id: str, *, status: str, prepared: _Prepared, attempted: Mapping[str, Any], + trace: Any) -> Outcome: + """把父 Run 里那次工具调用的结果收成一份与 `execute` 同形的 Outcome(见 `execute_prepared`)。 + + 结果取的是那次调用的**完整产出**(封存证据里按节点取它最后一次的产出工件),不是 tool.end 那个截到 2000 个字符的 + 预览:一次口径查询可能交回好几条查询,预览读不全。产出不在(父 Run 没跑成、工具没交出结果)时照实报 ok=False。""" + payload = await _tool_payload(parent_run_id) + if payload is None: + return _failed_outcome(parent_run_id, status=status, prepared=prepared, attempted=attempted, trace=trace) + problems = [dict(p) for p in payload.get("problems") or []] + # 固定的是发布物:子运行跑的必须就是这一层固定并授权过的那一版(推荐版在这中间换过就照实说,不把另一版当这一版交出) + ran_version = int(payload.get("version") or prepared.resolved.version) + if ran_version != int(prepared.resolved.version): + problems.append(_problem( + VERSION_MOVED, f"这次执行使用的是 v{ran_version},不是这一层固定并授权过的 " + f"v{int(prepared.resolved.version)}:推荐版在中途换过,请重新发起")) + return Outcome( + run_id=parent_run_id, status=str(payload.get("status") or status), + ok=bool(payload.get("ok")) and not any(str(p.get("code")) == VERSION_MOVED for p in problems), + workflow_id=str(payload.get("workflow_id") or prepared.resolved.workflow_id), + card_id=str(payload.get("card_id") or prepared.loaded.node_id), version=ran_version, + explicit_version=bool(payload.get("explicit_version")), purpose=str(payload.get("purpose") or DEFAULT_PURPOSE), + publication=dict(payload.get("publication") or {}), selection=dict(payload.get("selection") or {}), + parameters=dict(payload.get("parameters") or {}), + metrics=tuple(dict(m) for m in payload.get("metrics") or []), + queries=tuple(dict(q) for q in payload.get("queries") or []), + data=dict(payload.get("data") or {}), quality=dict(payload.get("quality") or {}), + problems=tuple(problems), trace=trace if trace is not None else payload.get("trace"), + measurement=_measurement_of(payload.get("measurement")), + execution_run_id=str(payload.get("run_id") or "") or None) + + +def _failed_outcome(parent_run_id: str, *, status: str, prepared: _Prepared, attempted: Mapping[str, Any], + trace: Any) -> Outcome: + """父 Run 没交出结果(失败、还挂着、工具没交回产出):照实交回 ok=False 的那一份,不编造指标。""" + if status == "running": + problems = [_problem(TIMEOUT, f"这次执行在 {attempted['timeout_s']} 秒内没有收尾:状态仍是运行中," + "请按 run_id 去看运行结果。超时不算成功")] + else: + problems = [_problem(EXECUTION, "这次口径查询没有交回结果(运行状态:" + status + ")")] + return Outcome( + run_id=parent_run_id, status=status, ok=False, workflow_id=str(prepared.resolved.workflow_id), + card_id=str(prepared.loaded.node_id), version=int(prepared.resolved.version), explicit_version=False, + purpose=DEFAULT_PURPOSE, publication=dict(prepared.publication_ref), + selection=_selection_of(prepared.closure), parameters={"values": dict(prepared.values)}, + metrics=(), queries=(), data={"as_of": None, "sources": [], "tables": [], "data_versions": {}, + "window": {}, "read": False}, + quality={"status": "unknown"}, problems=tuple(problems), trace=trace) + + +async def _tool_payload(run_id: str) -> dict[str, Any] | None: + """父 Run 里那个口径查询节点交回的完整产出;不是口径查询的结果(没跑、跑成别的样子)返回 None。""" + from app.engine.evidence_reader import read_sealed + + try: + sealed = await read_sealed(run_id) + except Exception: # noqa: BLE001 - 证据读不出来只影响这一份结果的还原,不该让调用变成 500 + logger.exception("prepare 的父运行 %s 读不出封存证据", run_id) + return None + payload = sealed.payload_of([PREPARED_NODE]) + if not isinstance(payload, Mapping): + return None + if str(payload.get("kind") or payload.get("tool") or "") != CALIBER_QUERY: + return None + return dict(payload) + + +def _measurement_of(record: Any) -> Measurement | None: + """子运行交回来的测量记录(dict)还原成 Measurement;形状不对就当没量到(None),不填 0 冒充。""" + if not isinstance(record, Mapping): + return None + phases, counts, ids = record.get("phases"), record.get("counts"), record.get("ids") + if not all(isinstance(part, Mapping) for part in (phases, counts, ids)): + return None + return Measurement(phases=dict(phases), counts=dict(counts), ids=dict(ids)) + + +# -------------------------------------------------------------------------- +# 内部:清单核验、判定、发起、等待、结果 +# -------------------------------------------------------------------------- + + +def _verified_manifest(resolved: Any, *, graph: Mapping[str, Any]) -> dict[str, Any]: + """这一版的发布清单:读得出来、内容哈希对得上、**就是这一版这一张图**的,约定和现在这一套兼容。 + + 老资产(这一版没有发布事件)走 GET/trial 那条老路,这里明确拒:没有清单就没有「固定发布执行」可核。""" + publication = resolved.publication + if publication is None: + raise QueryCoreRefused( + f"「{resolved.workflow_id}」v{resolved.version} 没有发布清单(加发布依据机制之前发布的老资产):" + "QueryCore 只按固定发布执行,老资产请走原来的试运行路径", MANIFEST_REQUIRED, status_code=409) + try: + content = publications.read(publication) + except publications.PublicationUnreadable as e: + raise QueryCoreRefused(e.message, MANIFEST_UNREADABLE, status_code=409, + problems=[{"code": e.code}]) from None + problems = publications.compiler_problems(content) + if problems: + raise QueryCoreRefused("这一版的发布清单不是按现在这套编译器/绑定/参数/解析器约定物化的,不按新规则重解释旧发布:" + + ";".join(str(p.get("message") or p.get("code")) for p in problems[:4]), + INCOMPATIBLE, status_code=409, problems=problems) + problem = publications.manifest_problem(publication, graph=graph) + if problem is not None: + raise QueryCoreRefused(str(problem.get("message") or "发布清单和这一版对不上"), + publications.BASIS_MISMATCH, status_code=409, problems=[problem]) + return content + + +async def _judged(session: Any, workflow: Any, resolved: Any, *, purpose: str, content: Mapping[str, Any], + graph: Mapping[str, Any]) -> dict[str, Any]: + """同一次判定(publications.judge,固定到刚解析出来的那一版):formal 依据不齐就拒,别的用途只读身份。 + + 判定用的版本是 `resolved.version`(已经固定),不重新解析推荐版;交回的那一份把清单引用和内容里的确定信息一起带上。""" + judged = await publications.judge(session, workflow, version=resolved.version, purpose=purpose) + if judged is None: + raise QueryCoreRefused(f"「{workflow.name}」v{resolved.version} 读不出来", VERSION_MISSING, status_code=404) + refusal = judged.refusal + if refusal is not None: + # formal:发布依据不齐(缺记录/不是 matched/没有认证审阅/只确认一部分/清单错图缺卡……)。机器码用 judge 的原码, + # 让入口和正式运行的说法一致;不换路、不降级成探索执行 + raise QueryCoreRefused(refusal[1], refusal[0], status_code=409, problems=list(judged.problems)) + return {**judged.as_dict(), + "workflow_id": resolved.workflow_id, "graph_hash": str(content.get("graph_hash") or ""), + "execution_hash": str(content.get("execution_hash") or ""), "format": publications.FORMAT, + "compiler": dict(content.get("compiler") or {}), "level": str(content.get("level") or ""), + "publication_id": str(getattr(resolved.publication, "id", "") or "")} + + +# -------------------------------------------------------------------------- +# K10:晚解析的数据源固定在**父 Run** 上 +# -------------------------------------------------------------------------- + + +def target_key(workflow_id: str, version: Any, card_id: str) -> str: + """这次执行钉住的固定目标:`<工作流>@<版本>:<卡>`。 + + 父 Run 记在补固定项上,用来认出「同一次运行里的这份固定是哪一份口径要的」——换了另一份口径(另一个工作流、 + 另一版、另一张卡)之后源又换过版本,就要明确说冲突,不能悄悄读另一版。""" + return f"{workflow_id}@{int(version)}:{card_id}" + + +def card_sources(graph: Mapping[str, Any], card_id: str) -> tuple[set[str], bool]: + """这一版图里那张口径卡读的取数源名,以及认不认得出来(纯函数,无 IO)。 + + 认得出:`card_inputs` 给出的取数节点绑的 `db_query__` / `db_schema__` 源。认不出(不是口径卡、式子里认不出取数 + 节点)就退回**这一版图里绑的全部数据源**(宁可多固定几个,也不漏),照实标成没认出来。""" + from app.engine.launch import tool_bindings + from app.engine.schema import GraphSpec + from app.look.calibers import card_inputs + from app.tools.datasource import source_of_tool + + inputs, _reason = card_inputs(dict(graph), card_id) + tools = [str(item.get("tool") or "") for item in inputs if isinstance(item, dict)] + sure = bool(tools) + if not sure: + tools = [name for _, name in tool_bindings(GraphSpec.model_validate(dict(graph)))] + return {source for tool in tools if (source := source_of_tool(tool)) is not None}, sure + + +async def pin_sources_for_parent(*, parent_run_id: str, resolved: Any, graph: Mapping[str, Any], + card_id: str, versions: Mapping[str, Any] | None, + emit: Any = None) -> dict[str, Any]: + """这次口径那一版读的源里,父 Run 还没固定的,按**父 Run 的**类别与主体补固定进父 Run 的记录(K10)。 + + 为什么不能在子运行里补(tools/datasource._pin_late_records):那条路按子运行的类别(exploratory)与主体重算 + 行级范围——正式父 Run 的 all 会被收成 mine/none;而且只写进子运行那一行:同一次运行里的两次调用各固定各的版本。 + + 这里固定的是**父 Run 自己已经授权的那一档**(`run_class` / `started_by`,同它发起时给别的源定范围的那一套), + 只记在父 Run 上,子运行照父 Run 那一份继承——不放大也不缩小。 + + - 已经固定过的源照旧复用(同一次运行里两次调用读同一版),不重新固定; + - 已经固定过、但那次固定属于**另一份口径目标**、而这个源现在的版本已经不是固定那一版:明确拒 + (`DATA_VERSION_CONFLICT`),不静默换一版; + - 父 Run 的记录读不回来(直接调工具的单测、在别处调用):原样交回,不固定也不报错。 + + 补固定本身在父 Run 上追加一条事件(`LATE_PIN_CODE` 的日志事件,带源、版本、口径目标、以及这次判定的行级范围): + 父 Run 的 `run.started` 已经落库、封不进去,只能追加。""" + from sqlalchemy import select + + from app.data import table_versions + from app.db.base import SessionLocal + from app.db.models import DataSource, Run + from app.tools.datasource import _late_lock + + out = dict(versions or {}) + names, _sure = card_sources(graph, card_id) + if not names: + return out + key = target_key(resolved.workflow_id, resolved.version, card_id) + pinned: list[dict[str, Any]] = [] + async with _late_lock(): + # 上传源要读当前指针到写进运行记录,持着版本存储的锁(同 tools/datasource._pin_late) + async with table_versions.pin_lock(), SessionLocal() as own: + run = await own.get(Run, str(parent_run_id)) + if run is None: + return out # 父 Run 的记录不在了:不在这里猜,交给调用方 + stored = dict(run.data_versions or {}) + for name in sorted(names): + row = (await own.execute(select(DataSource).where( + DataSource.name == name, DataSource.enabled.is_(True)))).scalar_one_or_none() + if row is None: + continue # 名字对不上(源被改名、停用、删了):查询自己会照实报错 + entry = stored.get(row.id) + if _pinned_version(entry) is not None: + _refuse_conflict(row, entry=entry, key=key, resolved=resolved, card_id=card_id, + current=await _current_version(own, row)) + out[row.id] = entry + continue + entry = await _pin_now(own, row, run_class=str(run.run_class or "exploratory"), + started_by=run.started_by) + if entry is None: + continue # 登记或数据文件不在:不固定,查询时照实报错 + entry.update(late=True, caliber=key) + stored[row.id] = entry + out[row.id] = entry + pinned.append({"source_id": row.id, "source": row.name, "entry": entry}) + if pinned: + run.data_versions = stored + await own.commit() + for item in pinned: + await _announce_pin(emit, **item, key=key, resolved=resolved) + return out + + +def _pinned_version(entry: Any) -> Any: + """这一项固定的是哪一版:上传源是快照 id,记录表是表的版本号。没固定(或形状不对)为 None。""" + if not isinstance(entry, dict): + return None + if isinstance(entry.get("snapshot"), str) and entry["snapshot"]: + return entry["snapshot"] + if isinstance(entry.get("version"), int) and isinstance(entry.get("seq"), int): + return int(entry["version"]) + return None + + +async def _current_version(session: AsyncSession, row: Any) -> Any: + """这个源现在这一版是哪一版(和 `_pinned_version` 同一种取值)。""" + if (getattr(row, "origin", None) or "manual") == "records": + from app.records.tables import table_of_source + + table = await table_of_source(session, row.id) + return int(table.version) if table is not None else None + snapshot = getattr(row, "current_snapshot_id", None) + return str(snapshot) if snapshot else None + + +async def _pin_now(session: AsyncSession, row: Any, *, run_class: str, started_by: str | None) -> dict[str, Any] | None: + """现在把这一版固定下来(和发起时固定用的是同一套):上传源取当前快照,记录表记高水位与**父 Run 的**行级范围。""" + from app.records.views import pin_entry + + if (getattr(row, "origin", None) or "manual") == "records": + return await pin_entry(session, row, run_class=run_class, started_by=started_by) + snapshot = getattr(row, "current_snapshot_id", None) + if not snapshot: + return None + return {"snapshot": str(snapshot), "name": row.name} + + +def _refuse_conflict(row: Any, *, entry: Mapping[str, Any], key: str, resolved: Any, card_id: str, + current: Any) -> None: + """这一项固定属于另一份口径目标、而这个源现在已经是另一版:明确拒,不静默换一版(同一次运行不能读两版数据)。 + + 消息要短:节点把它交给 describe_exception 时会按 240 个字符截断,写太长机器码就被截掉了。精确的值放在 + problems 里(程序看那一份)。""" + owned_by = str(entry.get("caliber") or "") + if not owned_by or owned_by == key or _pinned_version(entry) == current: + return + raise QueryCoreRefused( + f"数据源「{row.name}」在这次运行里固定的是 {_version_text(row, _pinned_version(entry))}," + f"这次要执行的口径「v{resolved.version}:{card_id}」引用的是 {_version_text(row, current)}:" + "同一次运行不能悄悄换一版数据。请重新发起运行,或让两份口径用同一版数据", + DATA_VERSION_CONFLICT, status_code=409, + problems=[{"code": DATA_VERSION_CONFLICT, "source": row.name, "pinned": _pinned_version(entry), + "current": current, "caliber": owned_by, "target": key}]) + + +def _version_text(source: Any, value: Any) -> str: + """报错里那一版的写法:上传源给快照 id 的前 12 位,记录表给版本号。""" + if value is None: + return "(读不出来)" + if (getattr(source, "origin", None) or "manual") == "records": + return f"记录表第 {value} 版" + return f"快照 {str(value)[:12]}" + + +async def _announce_pin(emit: Any, *, source_id: str, source: str, entry: Mapping[str, Any], key: str, + resolved: Any) -> None: + """把这次补固定写进父 Run 的事件流(`run.started` 已经落库,补不进去,只能追加)。""" + import inspect + + if emit is None: + return + from app.core.events import EventType + from app.tools.datasource import LATE_PIN_CODE + + pinned_text = (str(entry.get("snapshot")) if entry.get("snapshot") + else f"记录表第 {entry.get('version')} 版、高水位 {entry.get('seq')}") + data = {"source_id": source_id, "source": source, "late": True, "caliber": key, "pinned_by": "caliber_query", + "workflow_id": resolved.workflow_id, "version": resolved.version, + **{k: entry.get(k) for k in ("snapshot", "seq", "rows", "viewer", "version") if entry.get(k) is not None}} + note = (f"数据源「{source}」发起时没有固定版本,这次口径查询在父运行上固定为当时的那一版({pinned_text})," + f"行级范围照父运行的授权({entry.get('rows') or '不适用'});之后继续运行、审批恢复、同一次运行里别的调用" + "都沿用这一版") + try: + out = emit(EventType.LOG, level="info", code=LATE_PIN_CODE, message=note, **data) + if inspect.isawaitable(out): + await out + except Exception: # noqa: BLE001 - 事件只是留痕,固定本身已经记进运行记录 + logger.warning("补固定的父 Run 事件没发出去(口径 %s@%s)", resolved.workflow_id, resolved.version, + exc_info=True) + + +async def _start(graph_spec: Mapping[str, Any], *, values: Mapping[str, Any], workflow: Any, resolved: Any, + closure: Any, publication_ref: Mapping[str, Any], purpose: str, actor: str | None, + trace: Any, parent_run_id: str | None = None, run_options: Mapping[str, Any] | None = None, + data_versions: Mapping[str, Any] | None = None) -> Any: + """起一次只读的探索运行:来源按 engine/origin 的常量记(口径固定执行), + origin 数据里带上这次固定的版本、清单、闭包身份、用途与 trace。 + + K10 父 Run 那条路(`caliber_query`):派生的探针运行是**明确的子运行**——origin 里记 `parent_run_id`,选项、固定的数据 + 版本照父 Run 原样带下去(遮罩、数据目录视图、上传/记录源版本固定一条不断),只读边界照旧一律加上。""" + from app.core.events import EventType + from app.engine.origin import origin_note + from app.engine.runner import run_manager + from app.tools.datasource import READ_ONLY_OPTION + + origin = { + "service": "querycore", "purpose": purpose, "workflow_id": resolved.workflow_id, + "version": resolved.version, "node_id": closure.source.get("card_id"), + "card": closure.source.get("card_id"), + "manifest": publication_ref.get("manifest"), "identity": publication_ref.get("identity"), + "selection_hash": closure.selection_hash, "closure_hash": closure.closure_hash, + "metric_ids": list(closure.metric_ids), "query_ids": list(closure.query_ids), + **({PARENT_RUN_KEY: str(parent_run_id)} if parent_run_id else {}), + **({"trace": trace} if trace is not None else {}), + } + data = {**origin, "actor": actor} + kind = origin_kind() + notes = [(EventType.RUN_ORIGIN, None, origin_note(kind, **data))] + # 父 Run 的选项照原样带下去(遮罩、数据目录视图……),只读边界一律加上:这次执行的取数一律只读 + options = {**dict(run_options or {}), READ_ONLY_OPTION: True} + try: + return await run_manager.start( + graph=dict(graph_spec), input_payload=dict(values), workflow_id=resolved.workflow_id, + workflow_name=str(workflow.name or ""), run_class="exploratory", version=resolved.version, + version_hash=str(getattr(resolved.row, "graph_hash", "") or ""), started_by=actor, + options=options, data_versions=dict(data_versions) if data_versions is not None else None, + notes=notes, origin_kind=kind, origin=origin) + except ValueError as e: + raise QueryCoreRefused(f"这次固定执行的图过不了校验:{e}", EXECUTION, status_code=409) from None + + +async def _await_run(run_id: str, *, timeout_s: float) -> str: + """进程内等这次运行收尾:先等执行任务(不阻塞事件循环),没完就看库里的状态,到点交回 running。 + + **超时不算成功**:还没到终态就照实回 running,run_id 交给调用方自己去看(同试跑接口的分寸)。""" + from app.db.base import SessionLocal + from app.db.models import Run + from app.engine.runner import run_manager + + loop = asyncio.get_running_loop() + deadline = loop.time() + max(0.0, float(timeout_s)) + while True: + async with SessionLocal() as poll: + row = await poll.get(Run, run_id) + status = str(row.status) if row is not None else "unknown" + if row is None or status in TERMINAL_RUN_STATUSES: + return status + remaining = deadline - loop.time() + if remaining <= 0: + return "running" + await run_manager.wait_idle(run_id, timeout=min(remaining, 0.5)) + + +async def _outcome(run_id: str, *, status: str, workflow: Any, resolved: Any, loaded: Any, closure: Any, + plans: Mapping[str, _Plan], values: Mapping[str, Any], ignored: Sequence[str], + publication_ref: Mapping[str, Any], purpose: str, attempted: Mapping[str, Any], + trace: Any, stages: _Stage) -> Outcome: + """收尾:按运行状态取证据、拼类型化结果、判「算成了没有」,并把这次量到的收成一份测量记录(K13)。""" + from app.db.base import SessionLocal + from app.db.models import Run + from app.engine.validation import validation_report + + problems: list[dict[str, Any]] = [] + metrics: list[dict[str, Any]] = [] + raw_metrics: dict[str, Any] = {} + queries: list[dict[str, Any]] = [] + trusted = False + #: 这一次收尾里几处共用的封存证据(见 _sealed_of):同一份快照不读三遍 + memo: dict[str, Any] = {} + async with SessionLocal() as poll: + row = await poll.get(Run, run_id) + finished = row.finished_at.isoformat() if row is not None and row.finished_at else None + error = row.error if row is not None else None + # K13:排队时长读运行记录上的那一项(老运行、还没收尾的运行没有它就是 None);其余几样要读到执行证据才有 + facts: dict[str, Any] = {"queue_ms": _queue_of(row), "database_ms": None, "llm_calls": None, "executed_sql": None} + if row is None: + # 运行记录读不回来(被清掉之类):交不回结果,也绝不冒充成功 + problems.append(_problem(NO_RUN, "这次执行的运行记录不在了:交不回结果")) + elif status == "succeeded": + try: + metrics, raw = await _metrics_from(run_id, card_id=str(loaded.node_id), metric_ids=closure.metric_ids, + memo=memo) + trusted = bool(raw.get("trusted")) + raw_metrics = raw.get("metrics") or {} + if not trusted: + problems.append(_problem(EVIDENCE, "这次运行的封存证据核验没通过:不能把结果当已核验的值交出")) + except Exception: # noqa: BLE001 - 证据读不出来(工件被改、读不回来)也不该让请求变成 500 + logger.exception("QueryCore 执行 %s 的指标证据读不出来", run_id) + problems.append(_problem(EVIDENCE, "这次运行的指标证据读不出来:不能把结果交出")) + try: + queries = await _queries_from(run_id, closure=closure, plans=plans, memo=memo) + except Exception: # noqa: BLE001 - 查询快照读不出来:交不回证据引用,照实说 + logger.exception("QueryCore 执行 %s 的查询证据读不出来", run_id) + problems.append(_problem(QUERY_MISSING, "这次运行的查询快照读不出来:证据引用交不回来")) + try: + # K13:数据库那一截(取数节点自己的执行时长)与真发出去的 SQL 条数按封存事件与逐次记录量。封存都得 + # 到这一步了还读不出来,就留 None——量不到是量不到,不拿计划条数或 0 顶上 + facts.update(_from_evidence(await _sealed_of(run_id, memo), closure)) + except Exception: # noqa: BLE001 - 量不出来不该影响结果本身 + logger.exception("QueryCore 执行 %s 的执行量测不出来", run_id) + elif status == "running": + problems.append(_problem(TIMEOUT, f"这次执行在 {attempted['timeout_s']} 秒内没有收尾:状态仍是运行中," + "请按 run_id 去看运行结果。超时不算成功")) + else: + problems.append(_problem(EXECUTION, error or "这次执行没有成功完成", status=status)) + + present = {str(m.get("id")) for m in metrics} + if row is not None and status == "succeeded": + # 指标/查询层面的问题只在「跑完了」时才说:没跑完谈不上缺指标,那条已经由 TIMEOUT/EXECUTION/NO_RUN 说了 + for metric_id in closure.metric_ids: + if metric_id not in present: + problems.append(_problem(METRIC_MISSING, f"点名的指标「{metric_id}」没有出现在结果里", + metric_id=metric_id)) + continue + if str(next(m for m in metrics if str(m.get("id")) == metric_id).get("status") or "") != "ok": + problems.append(_problem(METRIC_NO_VALUE, f"指标「{metric_id}」这次没有可用的标量值", + metric_id=metric_id)) + if any(m.get("masked") for m in metrics): + problems.append(_problem(METRIC_MASKED, "有指标的值被遮罩:不把遮罩值当结果交出")) + missing_queries = [q["query_id"] for q in queries if not q.get("found")] + if missing_queries: + problems.append(_problem(QUERY_MISSING, "这次要执行的查询没有留下快照:" + "、".join(missing_queries), + query_ids=missing_queries)) + for query in queries: + if query.get("rebound"): + problems.append(_problem(REBOUND, f"查询「{query['query_id']}」:{query['rebound']}", + query_id=query["query_id"])) + if not metrics: + problems.append(_problem(EMPTY, "这次执行没有任何指标结果:空结果不算成功")) + + quality = validation_report(list(raw_metrics.values()), execution=status, trusted=trusted) + parameters = { + "adapter": _plans_adapter(plans), + "values": dict(values), + "ignored": list(ignored), + "contract": [dict(c) for c in _contract_of(loaded)], + "queries": [plan.as_dict() for plan in plans.values()], + } + measurement = _measurement(stages, run_id=run_id, workflow_id=str(resolved.workflow_id), + card_id=str(loaded.node_id), version=int(resolved.version), closure=closure, + status=status, problems=problems, queries=queries, facts=facts, trace=trace) + return Outcome( + run_id=run_id, status=status, ok=not problems and status == "succeeded" and bool(metrics), + workflow_id=str(resolved.workflow_id), card_id=str(loaded.node_id), version=int(resolved.version), + explicit_version=bool(resolved.explicit), purpose=purpose, publication=dict(publication_ref), + selection=_selection_of(closure), parameters=parameters, metrics=tuple(metrics), queries=tuple(queries), + data=_data_of(queries, loaded=loaded, values=values, finished=finished), + quality=quality, problems=tuple(problems), trace=trace, measurement=measurement) + + +def _plans_adapter(plans: Mapping[str, _Plan]) -> str: + from app.ledger import params + + for plan in plans.values(): + if plan.material.get("adapter"): + return str(plan.material["adapter"]) + return params.ADAPTER + + +def _contract_of(loaded: Any) -> list[dict[str, Any]]: + from app.ledger import params + + return params.contract(loaded.entry_fields) + + +def _selection_of(closure: Any) -> dict[str, Any]: + """这次的 selection/closure 身份:算哪些指标、执行哪几条查询(含共享 SQL 还在算谁)、解析器版本与两份哈希。""" + return {**closure.summary(), "card_metric_ids": list(closure.card_metric_ids)} + + +def _data_of(queries: Sequence[Mapping[str, Any]], *, loaded: Any, values: Mapping[str, Any], + finished: str | None) -> dict[str, Any]: + """这次数据读了什么、什么时候读的:来源、表、上传源的数据版本、这次的时间窗口。""" + from app.ledger import params + + sources: set[str] = set() + tables: set[str] = set() + versions: dict[str, Any] = {} + for query in queries: + if query.get("data_source"): + sources.add(str(query["data_source"])) + tables.update(str(t) for t in query.get("tables") or []) + if query.get("data_version") and query.get("data_source"): + versions[str(query["data_source"])] = query["data_version"] + declared = params.declared(loaded.entry_fields) + window = {str(name): value for name, value in values.items() + if (params.field_type(declared.get(name) or {}) in _TIME_TYPES + or (isinstance(value, str) and _DATE_LIKE.match(value.strip())))} + return {"as_of": finished, "sources": sorted(sources), "tables": sorted(tables), + "data_versions": versions, "window": window, "read": bool(queries)} + + +# -------------------------------------------------------------------------- +# K10:父 Run 的工具入口(caliber_query) +# -------------------------------------------------------------------------- + + +class CaliberQueryArgs(BaseModel): + """caliber_query 的参数:口径身份(workflow + card)、要算的指标、这次入口的类型化取值。 + + **参数到此为止**:用途(formal/compose)、认证主体、父 Run 身份、固定的数据版本都由父 Run 的上下文定,参数里没有 + 也传不了;点名版本留给别的调用方,父 Run 走的是「读一次推荐版并当场固定」。""" + + workflow: str = Field(description="口径所在的工作流:工作流 id,或唯一的工作流名字") + card: str = Field(description="工作流里那张口径卡的节点 id:一次只算一张卡") + metric_ids: list[str] = Field(min_length=1, description="这次要算的指标 id,可以多个;空的不当整卡") + inputs: dict[str, Any] = Field(default_factory=dict, + description="这次入口的取值:{字段:值},按入口声明的类型校验(日期写 YYYY-MM-DD)") + + +@register( + name=CALIBER_QUERY, + category="口径", + effect="read", + description="按一份已发布的固定口径取一次数(工作流 + 口径卡 + 指定指标 + 入口取值),交回类型化的指标值和每条查询的" + "证据引用——数出自哪一版、哪份发布清单、哪条 SQL 的执行都核得到。只读,不改数据。", + args_schema=CaliberQueryArgs, +) +async def caliber_query(ctx: ToolContext, **kwargs: Any) -> dict[str, Any]: + """父 Run 的工具入口(K10):用**父 Run 的上下文**按固定口径执行一次,当场 await 收尾,把查询证据接回父 Run。 + + - 用途由父 Run 定:`formal` 的父 Run 走 `execute_formal`(同一套 `publications.judge`,发布依据不齐就拒,不换路、 + 不降级成探索),别的(交互、画布、试用)走 compose——拿不到正式身份; + - 父 Run 固定的上传/记录源版本、选项(遮罩、只读、数据目录视图)与来源照原样带进派生的子运行(origin 里记 + `parent_run_id`),不失去父关系;超时、失败、遮罩、空指标照实交回 `ok=False`,绝不冒充成功; + - 交回的结果与交互工作台同一种形状:metrics + queries 数组(每条带 query_id / execution_id / attempt、工件、来源、 + 参数材料),节点据此把每条 query artifact 以合法引用记进父 Run 的证据。""" + args = CaliberQueryArgs(**kwargs) + from app.db.base import SessionLocal + from app.db.models import Run + + parent = str(getattr(ctx, "run_id", "") or "") + if not parent: + raise QueryCoreRefused("caliber_query 只能在一次运行里调用:没有父运行,就没有证据可以接回去", + NO_PARENT, status_code=409) + try: + async with SessionLocal() as session: + # 用途、主体、选项、固定的数据版本一律以**父运行的记录**为准(engine/runner 存下的那一份),ToolContext + # 里那几项只当兜底:工具在哪条路上被调(调用工具节点、Agent、协作成员)都拿到同一个答案,不会被某个节点 + # 少的几项悄悄换掉。父运行记录读不回来(单测直接调工具)就按 ToolContext 给的算。 + parent_row = await session.get(Run, parent) + if parent_row is not None: + run_class = str(parent_row.run_class or "") + options = dict(parent_row.options or {}) + versions = parent_row.data_versions + actor = parent_row.started_by + trace = parent_row.origin + else: + run_class = str(getattr(ctx, "run_class", "") or "") + options = dict(getattr(ctx, "run_options", None) or {}) + versions = getattr(ctx, "data_versions", None) + actor = getattr(ctx, "started_by", None) + trace = getattr(ctx, "origin", None) + purpose = HOST_PURPOSE if run_class == "formal" else DEFAULT_PURPOSE + declared_budget = options.get(BUDGET_OPTION) + workflow_id = await _workflow_id(session, args.workflow) + outcome = await execute( + session, workflow_id=workflow_id, card_id=args.card, metric_ids=args.metric_ids, inputs=args.inputs, + purpose=purpose, actor=actor, parent_run_id=parent, run_options=options, + data_versions=versions if isinstance(versions, Mapping) else None, + budget=declared_budget if isinstance(declared_budget, Mapping) else None, trace=trace, + # 晚解析的源(发布得晚、推荐版变了、动态引用)在父 Run 上补固定:把这次补固定追加进父 Run 的事件流 + emit=getattr(ctx, "emit", None)) + except QueryCoreRefused as e: + # 拒(没发起)在工具这一层是一条失败,不是一份结果:机器码带在报错里,节点、Agent 的失败信息按它认这一档, + # 不用去解析中文 + raise ValueError(f"{e.message}({e.code})") from None + return {"tool": CALIBER_QUERY, "kind": CALIBER_QUERY, **outcome.as_dict()} + + +async def _workflow_id(session: AsyncSession, ref: str) -> str: + """工具参数里的工作流:先按 id 认;认不到再按名字认,且只有一个同名时才认(多个同名照实拒,不替它挑一个)。""" + from sqlalchemy import select + + from app.db.models import Workflow + + ref = str(ref or "").strip() + workflow = await session.get(Workflow, ref) + if workflow is not None: + return workflow.id + found = list((await session.execute(select(Workflow).where(Workflow.name == ref))).scalars()) + if not found: + raise QueryCoreRefused(f"找不到口径所在的工作流「{ref}」:可能已被删除,或名字写错了", + NOT_FOUND, status_code=404) + if len(found) > 1: + raise QueryCoreRefused(f"有 {len(found)} 个工作流都叫「{ref}」:请用工作流 id 点名要哪一份口径", + NOT_FOUND, status_code=409) + return found[0].id + + +def query_entries(payload: Any) -> list[dict[str, Any]]: + """`caliber_query` 交回的结果里的查询条目——**多条**(一张卡这一次可能执行好几条取数)。 + + 不是 caliber_query 的结果(名字不对、没有 queries 数组)返回空列表:调用方按工具名认身份,不看结果长得像不像。 + 单条查询的数据源工具走 engine/evidence.query_entry_fields,不走这里;两支都由 capabilities.registry.query_items + 摊成同一种条目,再由 snapshot_owned 逐条认工件。""" + data = payload + if isinstance(data, str): + text = data.lstrip() + if not text.startswith("{"): + return [] + try: + data = json.loads(text) + except ValueError: + return [] + if not isinstance(data, dict) or str(data.get("kind") or data.get("tool") or "") != CALIBER_QUERY: + return [] + out: list[dict[str, Any]] = [] + for item in data.get("queries") or []: + if not isinstance(item, Mapping) or not item.get("artifact"): + continue + out.append({ + "artifact": str(item["artifact"]), + # 数据源的源名:和数据源查询的条目写在同一个位置(证据面板、遮罩、数据目录按它认源) + "source": item.get("data_source"), + # 这条查询在这份口径里的出处(workflow + 版本 + 取数节点):数据源条目没有这一项 + "origin": dict(item["source"]) if isinstance(item.get("source"), Mapping) else None, + "columns": [str(c) for c in item.get("columns") or []], + "rows": int(item.get("row_count") or 0), "truncated": bool(item.get("truncated")), + "query_id": item.get("query_id"), "execution_id": item.get("execution_id"), + "attempt": item.get("attempt"), + **({"call_id": item["call_id"]} if item.get("call_id") else {}), + # 复算要的材料:这次参数输入的哈希、源模板哈希、承载方式与绑定指纹(值本身与 SQL 正文都不在这里) + **({"parameters": dict(item["parameters"])} if isinstance(item.get("parameters"), Mapping) else {}), + **({"tables": [str(t) for t in item["tables"]]} if item.get("tables") else {}), + **({"schema_artifact": item["schema_artifact"]} if item.get("schema_artifact") else {}), + }) + return out + + +__all__ = ["BUDGET_OPTION", "BUDGET_REFUSED", "CALIBER_QUERY", "CARD_MISSING", "DEFAULT_MAX_QUERIES", + "DEFAULT_PURPOSE", "DEFAULT_TIMEOUT_S", "EMPTY", "EVIDENCE", "EXECUTION", "HOST_PURPOSE", "INCOMPATIBLE", + "INPUTS_REFUSED", "MANIFEST_REQUIRED", "MANIFEST_UNREADABLE", "METRIC_MASKED", "METRIC_MISSING", + "METRIC_NO_VALUE", "NOT_AUTHORIZED", "NOT_FOUND", "NOT_PUBLISHED", "NO_PARENT", "NO_RUN", + "OUTPUT_UNSUPPORTED", "PARAMETERS_REFUSED", "PARENT_RUN_KEY", "PHASES", "PREPARED_INPUT", "PREPARED_NODE", + "PREPARED_OUTPUT", "QUERY_MISSING", "REBOUND", "REFUSAL_CODES", "SELECTION_REFUSED", "UNKNOWN_INPUT", + "VERSION_MISSING", "VERSION_MOVED", "CaliberQueryArgs", "Measurement", "Outcome", "QueryCoreRefused", + "caliber_query", "exact", "execute", "execute_formal", "execute_prepared", "origin_kind", "prepared_graph", + "query_entries", "typed"] diff --git a/backend/app/ledger/recall.py b/backend/app/ledger/recall.py index 5d87fb28..7c1755c8 100644 --- a/backend/app/ledger/recall.py +++ b/backend/app/ledger/recall.py @@ -13,7 +13,8 @@ metrics_from 指向召回卡;不加报告、不调模型)。两版在同一次运行里查同一份数据,差值只反映口径;数据随时间的变化另外拿 原答案当时的值对照着说(task_payload 的 original)。 - 不能重算的照实记「无法重算:原因」,不发起:口径的数据部分不能复用(derive.NotDerivable)、新版里没有这张口径卡、两版 - 没有同名的指标、新版入口要的参数这一组里没有或不合规(compose.check_inputs 同一套校验)、新版的图里会写外部系统 + 没有同名的指标、入口要的参数这一组里没有或不合规——新版和旧版各自的取数模板都判(ledger/params 的参数完整性,值就是 + 这一组的输入;新版一侧 compose.check_inputs 同一套校验,旧版一侧 build_plan 的 parameter_problem 补上)、新版的图里会写外部系统 (apps/backfill.graph_external_write,和按新口径补算、按口径出具同一个判断)。新版图里别处有人工节点、按流程使用不安全的 照样重算:召回图只有两版的取数和口径卡,碰不到它们(口径卡上游的人工节点 derive 已经认作数据部分不能复用);「按新版 重新出具」走完整的正式运行,仍按 graph_side_effect 全套拒绝(ledger/issue.check_target)。 @@ -100,6 +101,8 @@ CARD_GONE = "新版 v{version} 里没有口径卡「{card}」" NO_COMMON = "新旧两版的口径卡没有同名的指标,比不了" SIDE_EFFECT = "「{name}」v{version}{reason},召回不代人做这些事" NEW_INPUTS = "新版 v{version} 的入口要的参数这一组里没有或不合规:{problem}" +#: 旧版一侧的同一句话(旧版独有的字段在这组里没有值、绑定出来的是空串、值承载不了……) +OLD_INPUTS = "旧版 v{version} 的入口要的参数这一组里没有或不合规:{problem}" NEW_GONE = "新版本不存在,可能已被删除" LAUNCH_REFUSED = "没能发起召回运行:{reason}" RUN_FAILED = "重算失败:{reason}" @@ -234,8 +237,29 @@ async def recall_runs(session: Any, workflow_id: str, new_version: int | None = return list((await session.execute(stmt.order_by(Run.created_at.desc(), Run.id.desc()))).scalars()) +def parameter_problem(pairs: Sequence[Pair], inputs: Mapping[str, Any]) -> str | None: + """这一组的参数按两版各自的取数模板各过一遍(ledger/params,trial、组合式问数、派生各入口同一套):模板引用了入口 + 没声明的字段、这次没有值(含绑定出来的是空串——空串不是值,是省略)、值承载不了(引号里带引号、裸写的不是数)都要在 + 计划这一步说清。计划说「可重算」、起飞了才失败,等于让人白等一次召回,也让人分不清「还剩几组没算」还算不算得完。 + + 两版各自判:新版一侧 compose.check_inputs 已经按同一份判断判过(值就是这一组的输入),这里按同一份输入把旧版一侧 + 补上——旧版独有的字段、旧版模板写在哪,只有旧版自己知道。认不出写法的取数模板在派生那一步(derive.load_pinned)已经 + 拒过,这里的问题都是缺参数 / 未声明 / 承载不了。运行时那道兜底照旧在(engine/nodes/tools 发查询前再判一次)。""" + from app.ledger import params + + for pair in pairs: + for wrapper, pinned in ((NEW_INPUTS, pair.new), (OLD_INPUTS, pair.old)): + problems = params.check_nodes(pinned.fetches, fields=pinned.entry_fields, values=inputs) + if problems: + return wrapper.format(version=pinned.version, problem=params.describe(problems)) + return None + + async def build_plan(session: Any, workflow_id: str, new_version: int) -> Plan: - """W 升到 N 的召回计划(见模块说明)。只读,不发起。""" + """W 升到 N 的召回计划(见模块说明)。只读,不发起。 + + 一组能不能重算,先把这一组的输入按两版各自的取数模板判过(parameter_problem),判不过的写进 group.problem + ——「新版入口要的参数这一组里没有或不合规」也可以是旧版一侧的同一个问题。""" from app.apps import versions as app_versions from app.apps.backfill import graph_external_write from app.ledger import compose, derive @@ -271,7 +295,7 @@ async def build_plan(session: Any, workflow_id: str, new_version: int) -> Plan: problems.append(CARD_GONE.format(version=new_version, card=old.card_title) if e.code == derive.GONE else NOT_REUSABLE.format(reason=e.message)) continue - if not {m["id"] for m in old.metrics} & {m["id"] for m in new.metrics}: + if not {m["id"] for m in _effective(old)} & {m["id"] for m in _effective(new)}: problems.append(NO_COMMON) continue pairs.append(Pair(old, new)) @@ -309,6 +333,8 @@ async def build_plan(session: Any, workflow_id: str, new_version: int) -> Plan: group.problem = NEW_INPUTS.format(version=new_version, problem=e.message) continue group.inputs = {**checked, **{k: v for k, v in group.binding.items() if k not in new_names}} + if problem := parameter_problem(pairs, group.inputs): + group.problem = problem existing = await recall_runs(session, workflow_id, int(new_version)) by_key: dict[tuple[int, str], Run] = {} for run in existing: @@ -335,6 +361,16 @@ _refusals: dict[tuple[str, int, int, str], str] = {} # ========================================================================== +def _effective(pinned: Any) -> list[dict[str, Any]]: + """这一版口径卡**这次真正会算出的**指标数组(唯一一份解释,见 engine/nodes/metrics.pinned_effective)。 + + 召回卡按 ``nodes.<卡>.metrics[i].value`` 取两版的数:i 必须落在运行时算出来的那份上。卡带了指标选择 + (caliber_from.metrics,K08)时,全量定义里的下标会对不上、静默取到别的指标;没有选择时就是全量定义,行为一字不变。""" + from app.engine.nodes.metrics import pinned_effective + + return pinned_effective(pinned) + + def _metric(mid: str, name: str, expression: str, src: Mapping[str, Any]) -> dict[str, Any]: out: dict[str, Any] = {"id": mid, "name": name, "unit": str(src.get("unit") or ""), "expression": expression} if src.get("decimals") is not None: @@ -354,8 +390,9 @@ def recall_card(pairs: Sequence[Pair]) -> tuple[dict[str, Any], list[dict[str, A k = 0 for i, pair in enumerate(pairs): old_prefix, new_prefix = derive.recall_prefixes(i) - new_by = {m["id"]: (j, m) for j, m in enumerate(pair.new.metrics)} - for idx, m in enumerate(pair.old.metrics): + old_metrics, new_metrics = _effective(pair.old), _effective(pair.new) + new_by = {m["id"]: (j, m) for j, m in enumerate(new_metrics)} + for idx, m in enumerate(old_metrics): if m["id"] not in new_by: continue j, nm = new_by[m["id"]] diff --git a/backend/app/ledger/reconcile.py b/backend/app/ledger/reconcile.py index 4de86bf5..fbd87016 100644 --- a/backend/app/ledger/reconcile.py +++ b/backend/app/ledger/reconcile.py @@ -22,8 +22,9 @@ 上的指标 id}),这个选择记进对账运行的 origin。 **多行结果**(这次的结果不止一行):被报告引用了的那几行(最多 MAX_ROWS 行),按维度列(不是数的列)经合并查询和口径 -取数的结果按键对齐(LEFT JOIN,按引用的先后排),每个被引用的行、每个被引用的列出一组对账指标。两边的列按位置配(列数 -不同时不猜,照实拒绝)。维度列是遮罩列、或者这次的结果里合并键不唯一时照实拒绝:前者对齐要用到遮住的值,后者对不准 +取数的结果按键对齐(LEFT JOIN,按引用的先后排),每个被引用的行、每个被引用的列出一组对账指标。对齐语句由服务端按维度值 +拼成字面 SQL,值里可能带 `{{ }}`:那个节点带参数契约(ledger/params 的 marker),运行时不再当模板渲染一遍。两边的列按位置配 +(列数不同时不猜,照实拒绝)。维度列是遮罩列、或者这次的结果里合并键不唯一时照实拒绝:前者对齐要用到遮住的值,后者对不准 是哪一行。被引用的列是遮罩列的同样不对账。 只读:派生图只查库、不写;使用者发起时带上 MASK_RESULTS / READ_ONLY(同问数据),搭建者也带 READ_ONLY。对账运行记在 @@ -33,6 +34,7 @@ from __future__ import annotations import json +from collections.abc import Mapping from dataclasses import dataclass, field from typing import Any @@ -110,14 +112,39 @@ def _needs_check(cand: dict[str, Any], fields: list[dict[str, Any]], hide: Any) return None -def actions_of(content: dict[str, Any], names: dict[str, str], hide: Any = None) -> list[dict[str, Any]]: +async def actions_of(session: Any, content: dict[str, Any], names: dict[str, str], hide: Any = None, *, + actor: Any = None) -> list[dict[str, Any]]: """比对工件里每条有相关口径的查询、每份相关口径一项「看差多少」:{kind: reconcile, query, workflow_id, version, node_id, - needs_check, check_reason?, binding(遮过的), fields}。界面据此摆按钮、要不要先核对参数;fields 是那一版口径的入口字段 - (名字、必填、有没有缺省值,比对工件里记的那一份),核对参数的表单照它画(缺的参数也写得出是哪一项)。""" + needs_check, check_reason?, binding(遮过的), fields, available}。界面据此摆按钮、要不要先核对参数;fields 是那一版口径的 + 入口字段(名字、必填、有没有缺省值,比对工件里记的那一份),核对参数的表单照它画(缺的参数也写得出是哪一项)。 + + `available`:这一项**当前这个人能不能真的执行**——按同一份资产授权判(`apps/access.caliber_role` 到 use 及以上,和 + QueryCore 固定执行、对账入口发起时那一道同一个判定),builder / admin / 关登录显式放行(全部为真)。`actor` 不给就取当前 + 请求的身份。账本投影按它决定留不留请求要用的身份(api 里 `POST /api/ledger/answers/{run_id}/reconcile` 要 `workflow_id` + + `version`):**只有 available 的那一项留着**——无权的那几项只是说明,不带身份也就发不出去;真发出去入口照样 403 + `querycore_not_authorized`(app/api/ledger.ensure_caliber_use)。""" + from app.apps.access import at_least, caliber_role + from app.auth.chat_policy import effective_actor, restricted_actor from app.ledger.labels import LEVEL_TEXT, binding_view hide = hide or (lambda _value: False) fields = {c.get("caliber"): c.get("fields") or [] for c in content.get("calibers") or []} + who = effective_actor(actor) + narrowed = await restricted_actor(session, who) + # 同一(工作流、版本)只判一次:一份工件里同一版口径常出现在好几十条候选里 + roles: dict[tuple[str, int], bool] = {} + + async def usable(cand: Mapping[str, Any]) -> bool: + if not narrowed: + return True + try: + key = (str(cand.get("workflow_id") or ""), int(cand.get("version"))) + except (TypeError, ValueError): # 版本认不成整数:这一项谁也用不了(发起时同样过不去) + return False + if key not in roles: + roles[key] = at_least(await caliber_role(session, who, key[0], key[1]), "use") + return roles[key] + out: list[dict[str, Any]] = [] for query in content.get("queries") or []: if query.get("status") not in ("related",): @@ -130,6 +157,7 @@ def actions_of(content: dict[str, Any], names: dict[str, str], hide: Any = None) "workflow_id": cand.get("workflow_id"), "version": cand.get("version"), "node_id": cand.get("node_id"), "workflow_name": names.get(str(cand.get("workflow_id") or "")), "level_text": LEVEL_TEXT.get(str(cand.get("level") or ""), ""), + "available": await usable(cand), "needs_check": why is not None, "binding": binding_view(cand.get("binding"), hide), "fallback": bool((cand.get("diff") or {}).get("fallback")), "fields": [{"name": str(f.get("name")), "required": bool(f.get("required")), @@ -281,6 +309,7 @@ def _four(n: str, label: str, ours: str, theirs: str, pair: Pair) -> list[dict[s def tail_nodes(plan: Plan, *, card_id: str, fetch_id: str) -> list[dict[str, Any]]: """派生图的 tail:(多行时)对齐的合并查询 + 对账卡。card_id、fetch_id 是图里口径卡、口径取数节点的 id。""" + from app.ledger import params from app.ledger.derive import ALIGN_ID, OURS_ID, RECONCILE_CARD, _node metrics: list[dict[str, Any]] = [] @@ -292,8 +321,12 @@ def tail_nodes(plan: Plan, *, card_id: str, fetch_id: str) -> list[dict[str, Any else f"cell(nodes.{fetch_id}, 0, {pair.column!r})") metrics += _four(str(j), pair.name or pair.ours, ours, theirs, pair) else: - nodes.append(_node(ALIGN_ID, "merge", "按维度对齐", inputs={"o": OURS_ID, "c": fetch_id}, - sql=align_sql(plan.keys, plan.pairs, plan.key_values))) + # 对齐语句由服务端按维度值拼成字面 SQL(值来自查询结果,可能带 {{ }}):带参数契约(与这条语句绑定哈希), + # 运行时不再当模板渲染一遍 + align = align_sql(plan.keys, plan.pairs, plan.key_values) + nodes.append(_node(ALIGN_ID, "merge", "按维度对齐", inputs={"o": OURS_ID, "c": fetch_id}, sql=align, + **{params.KEY: params.marker(rendered=align, + source={"kind": "reconcile", "node_id": ALIGN_ID})})) for i, row in enumerate(plan.key_values): where = ",".join(f"{ours}={v}" for (ours, _), v in zip(plan.keys, row)) # 先核对第 i 行就是这一组的维度:重跑时这次的结果缺了一行、某个维度多出一行(口径那边重复),合并结果会错位, @@ -533,6 +566,17 @@ class Request: pairs: Any = None +def pinned_effective(pinned: Any) -> list[dict[str, Any]]: + """这张口径卡**这次真正会算出的**指标数组(唯一一份解释,见 engine/nodes/metrics.pinned_effective)。 + + ``nodes.<卡>.metrics[i]`` 的 i 落在这一份上,所以按位置配列、建 ``nodes.<卡>.metrics[i].value`` 引用时只用它:卡带了 + 指标选择(caliber_from.metrics,K08)时,全量定义里的下标和运行时算出来那份对不上,照全量定下标会静默取到别的指标。 + 没有选择时就是全量定义,行为一字不变。""" + from app.engine.nodes.metrics import pinned_effective as _pinned_effective + + return _pinned_effective(pinned) + + async def reconcile(run_id: str, req: Request, *, principal: Any) -> Run: """对这次运行的一条查询和一份相关口径对一次账:派生只读图、发起探索运行(来源 reconcile)。不能对的抛 ReconcileRefused。""" from app.api.deps import can_read_run @@ -618,7 +662,7 @@ async def reconcile(run_id: str, req: Request, *, principal: Any) -> Run: template = str(((fetch.get("data") or {}).get("config") or {}).get("args", {}).get("sql") or "") plan = plan_pairs(ours_columns=columns, ours_rows=rows, hidden=hidden, caliber_columns=_caliber_columns(template, inputs, list(pinned.entry_fields), kind, schema), - metrics=pinned.metrics, fetch=str(fetch["id"]), card=pinned.card_title, + metrics=pinned_effective(pinned), fetch=str(fetch["id"]), card=pinned.card_title, fallback=bool((cand.get("diff") or {}).get("fallback")), chosen=req.pairs, referenced=_referenced(sealed, req.query), projected=cand.get("projection"), cells=query.get("cells"), caliber=key) @@ -653,5 +697,5 @@ def build(pinned: Any, *, sql: str, tool: str, plan: Plan, inputs: dict[str, Any __all__ = ["CHECK_INPUTS", "MAX_COLUMNS", "MAX_ROWS", "NEEDS_PAIRS", "ORIGIN", "REFUSED", "Pair", "Plan", - "ReconcileRefused", "Request", "actions_of", "align_sql", "build", "plan_pairs", "reconcile", - "reconcile_groups", "reconciled_runs", "reconciled_view", "tail_nodes"] + "ReconcileRefused", "Request", "actions_of", "align_sql", "build", "pinned_effective", "plan_pairs", + "reconcile", "reconcile_groups", "reconciled_runs", "reconciled_view", "tail_nodes"] diff --git a/backend/app/ledger/reimport.py b/backend/app/ledger/reimport.py new file mode 100644 index 00000000..8a62d152 --- /dev/null +++ b/backend/app/ledger/reimport.py @@ -0,0 +1,1323 @@ +"""增量重导入与 B / L / R 三方合并(K11):把新一段材料重新抽成候选 R,和当前图 L、字段基线 B 逐字段比。 + +**三个东西各自是什么、谁跟谁走。** + +- **B**(baseline)是「上一次被接受的导入值」:K05 首次接受导入那一刻、按 metric_id + field_path 存下的不可变工件 + (app/ledger/fieldbaseline.py)。它只由「接受一次导入」推进,**只按被接受的那些字段往前走**;没接受的冲突一格不动。 +- **L**(live)是当前人工维护的图:口径卡上的指标。字段操作(K03)、整份换指标改的都是 L,改 L 一个字都不动 B。 +- **R**(重导入候选)是这次抽取出来的新说法。R 只生成候选,**不改 L**:要不要落到图上,由人按字段接受。 + +**按什么对齐。** 只认两样:稳定的 metric_id(候选显式带着、或者人指定),和**来源证据**(引用指向哪几段)。名字像不像 +不参与自动合并——同名不同范围(同一个名字、引的原文不是同一段)必须人来定,机器不替人猜「这说的是同一条指标」。 +按来源证据对上的依据优先取 B 的引用(那是「上次被接受时引的段落」);B 不可用时退回 L 现在引的段落。对上了不止一条 +(歧义)也交给人。 + +**baseline_unknown 不假装有基线。** 老草稿没有 B、或 B 读不回来时,不能拿 L 现在的内容冒充 B,也**不能假设 L = B**: +对齐上的每一项都标成「需要人工对齐」,逐字段由人决定,谁都不自动落。B 只在人明确接受那一刻、按接受的那几格从空建起来 +(见 fieldbaseline.advance)。 + +**逐字段的三方状态**(机器按它判能不能接受,见 FIELD_STATES):无冲突更新 / 人工修改冲突 / 新增候选 / 缺失候选四 +种,另加「不变」和「需要人工对齐」(没有可比基线时的兜底)。 + +| 状态 | 什么时候 | 能不能接受 | +| --- | --- | --- | +| update(无冲突更新) | R 和 B 不同,L 还停在 B 上 | 能:`auto` 一次收掉 | +| conflict(人工修改冲突) | R 和 B 不同,L 已经被人工改过 | 要人点名接受(接受 = 取 R;拒绝 = 留 L) | +| new(新增候选) | R 有这个字段,B 和 L 都没有 | 能 | +| missing(缺失候选) | R 这次没提取到这个字段 | **不能**:漏提取不当删除,L 的这一格原样留着 | +| manual(需要人工对齐) | 没有基线可比(baseline_unknown) | 要人点名接受 | +| unchanged(不变) | R 和 L 已经一致,或 R 和基线一致(同一原文重提) | 不用接受;人工覆盖不会被悄悄改回去 | + +**来源里的段落没给过模型,就不能当引用。** 候选的引用只留 `visible_chunk_ids` 里真的进了这次提示的段落,其余一律丢掉 +并记进 align.invisible_citations——引用一段模型没看到的原文,不算出处(和 K05 引用核对同一条规矩)。 + +**任务进度不是 B。** run.checkpoint 只记「哪些工作项还没做完、哪些字段已经接受」,重启后据此显式恢复(resume)。 +和 K05 一样:checkpoint 记的是任务恢复要用的东西,B 在草稿 payload 的 field_baseline 上。 + +**接受一次字段是原子的。** 「L 新增一版」和「B 往前推一格」必须在同一次提交里落地,否则会出现「L 提交了、B 永远没 +推进」的空档(重试幂等回放,B 却读不回来)。所以顺序固定:先在图拷贝上改完(不写库)→ 先写**不可变的新 B 工件** +(写失败就让整次失败,L 不落;万一后面回滚,留下的是没人引用的孤儿工件,可以接受)→ **一个**数据库事务提交 L 新版本、 +工作项决定、草稿上的新 B 引用与历史、幂等键 → 提交后只做读侧重算。全程只有一次提交。 + +**工作项的身份是持久对齐键,不是位置。** 一条工作项的键 = 稳定 metric 身份 + 规范化来源证据(段落 id),存在 +`CaliberImportItem.align_key` 上;恢复 / 重跑按它认项,候选顺序变了、条数变了都不会把接受 / 拒绝的决定搬到别的项上。 +每项自己记着它那一轮的可见段落和引用证据,不被新一轮覆盖。接口定位工作项按 `item_id`;旧调用只给 `metric_id` 时要求它 +唯一对得上一条(重复候选回 `item_ambiguous`,**不取最后一条**)。`metric_id` 只在候选带着**唯一的**编号、或按来源证据 +唯一对上时才写;模型跨组重号(每组各自从 m1 编起)不当稳定身份。 + +**失败的候选一格都不能接受。** 引用一段都没核对上(没给过模型的段落 / 模型没给引用)的候选整条 `failed`:逐格 +`acceptable=false`,明确去接受回 `item_failed`,auto 直接跳过——尤其不能用空的 R 把 citations 清掉。 + +**接受之前再看一眼 L。** 每项记着「算候选时那条指标的指纹」;接受时和现在图上的比,对不上就回 `import_stale_l` +(客户端只把 `expected_revision` 更新到最新一版也不行),要人 `POST …/refresh` 按现在的口径重算三方、重新确认。 +""" +from __future__ import annotations + +import copy +from collections.abc import Mapping, Sequence +from typing import Any + +from sqlalchemy import select +from sqlalchemy.exc import IntegrityError + +from app.core import job_runtime as runtime +from app.db.base import SessionLocal, utcnow +from app.db.models import CaliberDraft, CaliberImportItem, CaliberImportRun, Chunk, DataSource, Document, Workflow +from app.ledger import fieldbaseline + +#: 逐字段三方状态(见模块说明)。机器按它判能不能接受,界面按它显示。 +FIELD_STATES = ("update", "conflict", "new", "missing", "manual", "unchanged") +#: 工作项(一条候选指标)的状态:对齐+三方算出来的 + 人处置之后的 +ITEM_STATUSES = ("pending", "update", "conflict", "new", "manual", "unchanged", "partial", + "accepted", "rejected", "failed") +#: 能接受的那几种字段状态:无冲突更新、人工冲突(接受=取R)、新增候选、需要人工对齐(baseline_unknown) +ACCEPT_STATES = ("update", "conflict", "new", "manual") +#: run 的状态(core/job_runtime 的那一套词) +RUN_STATUSES = ("queued", "running", "succeeded", "partial", "failed", "cancelled", "interrupted") + +#: 遇到不能按预期继续时的机器码(接口一律带 code 回) +IMPORT_UNAVAILABLE = "import_unavailable" +IMPORT_REVISION_REQUIRED = "revision_required" +IMPORT_STALE_REVISION = "stale_revision" +IMPORT_IDEMPOTENCY_CONFLICT = "idempotency_conflict" +IMPORT_ITEM_UNKNOWN = "item_unknown" +IMPORT_FIELD_UNKNOWN = "field_unknown" +IMPORT_FIELD_NOT_ACCEPTABLE = "field_not_acceptable" +IMPORT_NOTHING_SELECTED = "nothing_selected" +IMPORT_ALREADY_RUNNING = "already_running" +#: 推进后的 B 工件写不进去(工件库故障):这次接受整体不落库(L 未提交),可以重试 +IMPORT_BASELINE_UNAVAILABLE = "baseline_unavailable" +#: 工作项定位:这次导入里对得上不止一条(重复 metric 候选 / 两条候选对到同一条指标)——按 item_id 指明 +IMPORT_ITEM_AMBIGUOUS = "item_ambiguous" +#: 这条工作项还没对齐到图上的指标(或整条失败):先人工对齐 / 重新抽取,再接受 +IMPORT_ITEM_UNALIGNED = "item_unaligned" +IMPORT_ITEM_FAILED = "item_failed" +#: 候选算出来之后 L 被人改过:不能只更新 expected_revision 就覆盖,要刷新三方、人重新确认 +IMPORT_STALE_L = "import_stale_l" +IMPORT_NOTHING_TO_RESUME = "nothing_to_resume" + +_MISSING = object() + + +class ImportRefused(Exception): + """这次导入操作不合规(接口照 status_code / code / message 回)。""" + + def __init__(self, status_code: int, message: str, code: str = IMPORT_UNAVAILABLE, *, + extra: dict[str, Any] | None = None) -> None: + super().__init__(message) + self.status_code = status_code + self.message = message + self.code = code + self.extra = extra or {} + + +# ========================================================================== +# 读值:B / L / R 各自的取法 +# ========================================================================== + + +def _same(left: Any, right: Any) -> bool: + """两个值是不是同一份(含「都没这一格」)。JSON 值直接比,不做隐式舍入。""" + if left is _MISSING or right is _MISSING: + return left is _MISSING and right is _MISSING + return bool(left == right) + + +def citation_chunks(container: Any) -> list[str]: + """一段内容(指标或一份基线值)里的引用段落 id,按出现顺序去重;`{citations:[…]}` 或 citations 数组都收。""" + citations = container.get("citations") if isinstance(container, Mapping) else container + out: list[str] = [] + for item in citations if isinstance(citations, (list, tuple)) else []: + if not isinstance(item, Mapping): + continue + chunk_id = item.get("chunk") or item.get("chunk_id") or item.get("chunkId") + if isinstance(chunk_id, str) and chunk_id and chunk_id not in out: + out.append(chunk_id) + return out + + +def visible_citations(metric: Any, visible_chunk_ids: Sequence[str]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]: + """把候选的引用分成两拨:真的进了这次提示的段落(留作引用),和没给过模型的段落(丢掉、记下来)。 + + 返回 (kept, invisible)。被丢掉的不能当引用:模型没看到那段原文,它对不上出处。 + """ + visible = {str(c) for c in visible_chunk_ids or []} + citations = (((metric or {}).get("definition") or {}).get("citations") + if isinstance((metric or {}).get("definition"), Mapping) else None) + kept: list[dict[str, Any]] = [] + invisible: list[dict[str, Any]] = [] + for item in citations if isinstance(citations, list) else []: + if not isinstance(item, Mapping): + continue + chunk_id = item.get("chunk") or item.get("chunk_id") or item.get("chunkId") + if isinstance(chunk_id, str) and chunk_id in visible: + kept.append(dict(item)) + else: + invisible.append(dict(item)) + return kept, invisible + + +def _live_value(metric: Any, path: str) -> Any: + """L 上某个字段路径的值;没有这一格就是 _MISSING。""" + if not isinstance(metric, Mapping): + return _MISSING + try: + return fieldbaseline.value_at(metric, path) + except KeyError: + return _MISSING + + +def _baseline_value(values: Any, path: str) -> Any: + return values[path] if isinstance(values, Mapping) and path in values else _MISSING + + +def field_state(*, baseline: Any, live: Any, candidate: Any, baseline_known: bool) -> str: + """一格的三方状态(见模块说明的四种 + 不变 + 需要人工对齐)。 + + baseline_known 是「这条指标有没有可比的基线(B 里收着它的接受值)」;**这一格**有没有基线还要看 baseline + 本身在不在。按字段推进出来的 B 常常只覆盖一部分格子:那些没覆盖到的格子照旧判 manual(不能因为这条指标有 + 别的格子的基线,就把这一格当成「L 还停在 B 上」)。 + """ + if candidate is _MISSING: + if live is _MISSING and (not baseline_known or baseline is _MISSING): + return "unchanged" # 本来就没有这一格,不算漏提取 + return "missing" # L 或 B 上有,R 这次没提到 → 漏提取不当删除 + if _same(candidate, live): + return "unchanged" # R 和 L 已经一致 + covered = baseline_known and baseline is not _MISSING + if covered and _same(candidate, baseline): + return "unchanged" # R 和基线一致:这次导入没有新说法,人工改过的 L 不动、也不报冲突 + if not covered: + if live is _MISSING: + return "new" # B、L 都没有,R 新提出来的字段 + return "manual" # 这一格没有可比基线 → 需要人工对齐,不自动落 + if live is _MISSING: + return "conflict" # L 这一格被删了(B 上有),R 又提了别的说法 → 要人定 + if _same(live, baseline): + return "update" # L 还停在 B 上 → 无冲突更新 + return "conflict" # L 已经被人工改过 → 人工修改冲突 + + +def _status_of_item(*, mode: str, fields: Mapping[str, Any]) -> str: + """一条候选指标的状态:对齐模式先定调,再看逐字段里最重的那一种。""" + if mode == "new": + return "new" + if mode == "manual": + return "manual" + states = {cell.get("state") for cell in fields.values() if isinstance(cell, Mapping)} + for state, status in (("conflict", "conflict"), ("manual", "manual"), ("update", "update"), + ("new", "new"), ("missing", "partial")): + if state in states: + return status + return "unchanged" + + +def item_status(*, mode: str, fields: Mapping[str, Any], accepted: Sequence[str], rejected: Sequence[str], + failed: bool = False) -> str: + """一条工作项现在的状态:还没决定的格子算状态;都决定完了就是 accepted / rejected。 + + 「已经决定的不再参与状态」是关键:接受一格之后它算 unchanged,不会让整条又退回 conflict。 + """ + decided = {str(p) for p in [*accepted, *rejected]} + remaining = {path: cell for path, cell in fields.items() + if isinstance(cell, Mapping) and path not in decided} + if failed and not accepted: + return "failed" + if not remaining or all(cell.get("state") == "unchanged" for cell in remaining.values()): + if accepted: + return "accepted" + return "rejected" if rejected else "unchanged" + return _status_of_item(mode=mode, fields=remaining) + + +# ========================================================================== +# 对齐(只认稳定 metric_id 和来源证据;不按名称) +# ========================================================================== + + +def align(*, candidate_id: str, candidate_citations: Sequence[Mapping[str, Any]], + live_metrics: Sequence[Mapping[str, Any]], baseline_values: Mapping[str, Any], + candidate_id_unique: bool = True) -> dict[str, Any]: + """把一条候选对到当前图的一条指标上:{metric_id, mode, reason, evidence, …}。 + + mode: + - metric_id:候选显式带着一个在图上存在、而且**这次导入里唯一**的稳定 id,且来源证据和图上那条不打架; + - evidence:按来源证据对上唯一一条(先比 B 的引用,B 没有这一格时退回比 L 的引用); + - new:都没对上——**不按名字合并**,交给人; + - manual:同一个 id 但来源证据不一致、或来源证据对上了不止一条:要人指定。 + + 只有 metric_id / evidence 两种模式才给 metric_id:对不上的(new / manual)一律留空,免得「对不上却挂了个 id」 + 被后面的写入当成已对齐。**跨组重号的候选 id 不当稳定身份**(candidate_id_unique=False,例如模型在两组里各自 + 从 m1 编起):这时只按来源证据对,不拿模型的新编号冒充稳定身份。 + """ + live_by_id = {str(m.get("id")): m for m in live_metrics or [] if isinstance(m, Mapping) and m.get("id")} + evidence = sorted(set(citation_chunks({"citations": list(candidate_citations or [])}))) + id_usable = bool(candidate_id) and candidate_id_unique + if id_usable and candidate_id in live_by_id: + live_evidence = sorted(set(citation_chunks((live_by_id[candidate_id] or {}).get("definition") or {}))) + if not evidence or not live_evidence or evidence == live_evidence: + return {"metric_id": candidate_id, "mode": "metric_id", "evidence": evidence, + "live_evidence": live_evidence, + "reason": "候选带着和图上一致的稳定 metric_id,来源证据也对得上"} + return {"metric_id": "", "mode": "manual", "evidence": evidence, "live_evidence": live_evidence, + "candidates": [candidate_id], + "reason": "候选带着和图上一样的 metric_id,但引的原文不是同一段(同名不同范围):请人工确认"} + + matches = [str(mid) for mid, values in (baseline_values or {}).items() + if evidence and sorted(set(citation_chunks((values or {}).get(fieldbaseline.CITATIONS_FIELD)))) == evidence] + basis = "baseline" + if not matches: + matches = [mid for mid, metric in live_by_id.items() + if evidence and sorted(set(citation_chunks((metric or {}).get("definition") or {}))) == evidence] + basis = "live" + note = "" + if candidate_id and not candidate_id_unique: + note = (f"候选 id「{candidate_id}」在这次导入里出现不止一次(跨组重号):不拿它当稳定身份," + f"只按来源证据对") + if len(matches) == 1: + out = {"metric_id": matches[0], "mode": "evidence", "evidence": evidence, "basis": basis, + "reason": f"按来源证据(引了同一段原文,依据取自{'字段基线 B' if basis == 'baseline' else '当前图 L'})" + f"对上了指标 {matches[0]}"} + if note: + out["identity_note"] = note + return out + if len(matches) > 1: + out = {"metric_id": "", "mode": "manual", "evidence": evidence, "basis": basis, "candidates": matches, + "reason": "来源证据对上了不止一条指标:请人工指定对哪一条"} + if note: + out["identity_note"] = note + return out + out = {"metric_id": "", "mode": "new", "evidence": evidence, + "reason": "没有对得上的指标(稳定 ID 和来源证据都没对上):名称相不相似不参与自动合并,请人工确认"} + if note: + out["identity_note"] = note + return out + + +def alignment_key(*, metric_id: str, evidence: Sequence[str]) -> str: + """一条工作项的**持久对齐键**:稳定 metric 身份 + 规范化来源证据(段落 id 排序去重)。 + + 恢复 / 重跑时按它认同一个工作项,不按候选位置:顺序变了、条数变了都不会把接受 / 拒绝的决定搬到别的项上。 + 对不上的候选 metric_id 是空串,键就只剩证据。 + """ + from app.core.artifact_store import canonical_json, content_hash + + return content_hash(canonical_json({"metric_id": str(metric_id or ""), + "evidence": sorted({str(e) for e in evidence or []})})) + + +def live_fingerprint(metric: Any) -> str: + """一条指标(L)在某个时刻的样子:逐字段值哈希的规范化指纹。 + + 接受之前拿它和现在图上的那条比:**L 在候选之后被人改过就不能落**(哪怕客户端把 expected_revision 更新成 + 最新的一版)——要人刷新三方、重新确认。给不出指标(对不上、或指标没了)时是空指标的指纹。 + """ + from app.core.artifact_store import canonical_json, content_hash + + cells = fieldbaseline.fields_of(metric) if isinstance(metric, Mapping) else {} + return content_hash(canonical_json({path: (cell or {}).get("hash") for path, cell in sorted(cells.items())})) + + +# ========================================================================== +# 组装工作项:一条候选 = 一条工作项,逐字段算三方 +# ========================================================================== + + +def build_item(*, seq: int, candidate: Mapping[str, Any], live_metric: Mapping[str, Any] | None, + align_info: Mapping[str, Any], baseline_values: Mapping[str, Any], baseline_known: bool, + visible_chunk_ids: Sequence[str]) -> dict[str, Any]: + """一条候选指标 → 一条工作项:过滤引用、逐字段算三方(不改 L、不改 B)。 + + align_info 是调用方(build_items / 人工对齐)已经算好的对齐依据;这里不再自己按名字或证据重对。 + **失败的工作项没有任何可接受的格子**:引用全都不可见时一条引用都留不下,这条整体标 failed, + 逐格 acceptable=false(尤其不能把 citations 接受成空——那等于把出处的证据删掉)。 + """ + metric = copy.deepcopy(dict(candidate or {})) + kept, invisible = visible_citations(metric, visible_chunk_ids) + definition = metric.get("definition") + definition = dict(definition) if isinstance(definition, Mapping) else {} + definition["citations"] = kept + metric["definition"] = definition + align_info = dict(align_info or {}) + align_info["visible_chunk_ids"] = sorted({str(c) for c in visible_chunk_ids or []}) + align_info["live_fingerprint"] = live_fingerprint(live_metric) + aligned_id = str(align_info.get("metric_id") or "") + cells = fieldbaseline.fields_of(metric) + fields: dict[str, Any] = {} + for path in fieldbaseline.field_paths(): + cell = cells.get(path) + candidate_value = cell.get("value") if isinstance(cell, Mapping) else _MISSING + live_value = _live_value(live_metric, path) + base_value = _baseline_value(baseline_values, path) + state = field_state(baseline=base_value, live=live_value, candidate=candidate_value, baseline_known=baseline_known) + fields[path] = { + "state": state, + "b": None if base_value is _MISSING else copy.deepcopy(base_value), + "l": None if live_value is _MISSING else copy.deepcopy(live_value), + "r": None if candidate_value is _MISSING else copy.deepcopy(candidate_value), + "b_present": base_value is not _MISSING, + "l_present": live_value is not _MISSING, + "r_present": candidate_value is not _MISSING, + "r_hash": cell.get("hash") if isinstance(cell, Mapping) else "", + "decided": None, + "acceptable": False, + } + if invisible: + align_info = {**align_info, "invisible_citations": invisible} + error = "" + status = _status_of_item(mode=align_info.get("mode") or "new", fields=fields) + if not kept: + # 一条引用都留不下:模型没看到那段原文,就不算出处(没有出处的定义不落,整条也不可接受) + status, error = "failed", "候选的引用指向的段落没有提供给模型:不能当出处,请重新抽取或人工补依据" + for path, cell in fields.items(): + cell["acceptable"] = _acceptable(status, cell.get("state"), bool(cell.get("r_present")), path, + cell.get("r")) + align_info["align_key"] = alignment_key(metric_id=aligned_id, evidence=kept_chunks(kept)) + return { + "seq": int(seq), + "metric_id": aligned_id, + "candidate_id": str(metric.get("id") or ""), + "name": str(metric.get("name") or ""), + "status": status, + "align": align_info, + "align_key": align_info["align_key"], + "fields": fields, + "accepted": [], + "rejected": [], + "applied_revision": None, + "error": error, + } + + +def kept_chunks(citations: Sequence[Mapping[str, Any]]) -> list[str]: + """留下来的引用指向的段落 id(工作项持久对齐键里的那一半「来源证据」)。""" + return sorted(set(citation_chunks({"citations": list(citations or [])}))) + + +def _acceptable(item_status: str, state: Any, r_present: bool, path: str, r_value: Any = None) -> bool: + """这一格能不能被接受:整条失败的不行;没提到、和现在一致的不行;引用不能被接受成空的。""" + if item_status == "failed" or not r_present: + return False + if path == fieldbaseline.CITATIONS_FIELD and not r_value: + return False # 出处不能被接受成空:那等于把证据删掉 + return state in ACCEPT_STATES + + +def build_items(*, candidates: Sequence[Mapping[str, Any]], live_metrics: Sequence[Mapping[str, Any]], + baseline_values: Mapping[str, Any], visible_chunk_ids: Sequence[str]) -> list[dict[str, Any]]: + """整批候选 → 一列工作项。先把候选按稳定 ID / 来源证据对到 L 上,再逐条算三方。 + + `baseline_values` 是 {metric_id: {field_path: 值}}(B 读回来的样子);某条候选 align 到的指标在它里面, + 这一条才有基线可比(baseline_known),否则逐字段判「需要人工对齐」。名称不参与对齐。 + + **跨组重号不当稳定身份**:模型可能每组各自从 m1 编起(draftplan 的 normalize_plan 就是这样),同一个编号出现 + 不止一次时只按来源证据对(见 align 的 candidate_id_unique)。 + """ + from collections import Counter + + live_by_id = {str(m.get("id")): m for m in live_metrics or [] if isinstance(m, Mapping) and m.get("id")} + ids = Counter(str((candidate or {}).get("id") or "") for candidate in candidates or []) + items: list[dict[str, Any]] = [] + keys: Counter[str] = Counter() + for position, candidate in enumerate(candidates or [], start=1): + kept, _invisible = visible_citations(candidate, visible_chunk_ids) + candidate_id = str((candidate or {}).get("id") or "") + probe = align(candidate_id=candidate_id, candidate_citations=kept, + live_metrics=list(live_by_id.values()), baseline_values=baseline_values or {}, + candidate_id_unique=bool(candidate_id) and ids[candidate_id] == 1) + metric_id = str(probe.get("metric_id") or "") + live_metric = live_by_id.get(metric_id) + baseline_known = bool(metric_id) and metric_id in (baseline_values or {}) + item = build_item(seq=position, candidate=candidate, live_metric=live_metric, align_info=probe, + baseline_values=(baseline_values or {}).get(metric_id) or {}, + baseline_known=baseline_known, visible_chunk_ids=visible_chunk_ids) + # 同键(同一身份 + 同一证据)的候选不止一条时按出现次序区分:它们本来就互为替身,谁先谁后不影响 + keys[item["align_key"]] += 1 + if keys[item["align_key"]] > 1: + item["align_key"] = f"{item['align_key']}#{keys[item['align_key']]}" + item["align"]["align_key"] = item["align_key"] + items.append(item) + return items + + +def refresh_item(item: Mapping[str, Any], *, live_metric: Mapping[str, Any] | None, + baseline_values: Mapping[str, Any], baseline_known: bool) -> dict[str, Any]: + """L 或 B 动过之后重算一条工作项的三方:已决定(接受/拒绝)的字段保持决定,只更新数值和状态。 + + 「不重复接受、也不因为别人的改动把人的决定抹掉」:已接受的格子状态只在被接受那次推进 B 时变过,之后照旧。 + **对齐键、来源证据、可见段落这一段原样保留**:它们是这一项自己的依据,不被新一轮重算覆盖;只刷新 + live_fingerprint(那是「上次按哪一版 L 算的三方」的比较锚点)。 + """ + fields = copy.deepcopy(dict(item.get("fields") or {})) + accepted = [str(p) for p in item.get("accepted") or []] + rejected = [str(p) for p in item.get("rejected") or []] + for path, cell in fields.items(): + if not isinstance(cell, Mapping): + continue + live_value = _live_value(live_metric, path) + base_value = _baseline_value(baseline_values, path) + candidate_value = cell.get("r") if cell.get("r_present") else _MISSING + cell["l"] = None if live_value is _MISSING else copy.deepcopy(live_value) + cell["l_present"] = live_value is not _MISSING + cell["b"] = None if base_value is _MISSING else copy.deepcopy(base_value) + cell["b_present"] = base_value is not _MISSING + if path in accepted: + cell["state"], cell["decided"] = "unchanged", "accepted" + elif path in rejected: + cell["decided"] = "rejected" + else: + cell["state"] = field_state(baseline=base_value, live=live_value, candidate=candidate_value, + baseline_known=baseline_known) + cell["decided"] = None + mode = str((item.get("align") or {}).get("mode") or "new") + failed = item.get("status") == "failed" + status = item_status(mode=mode, fields=fields, accepted=accepted, rejected=rejected, failed=failed) + for path, cell in fields.items(): + if isinstance(cell, dict): + cell["acceptable"] = _acceptable(status, cell.get("state"), bool(cell.get("r_present")), path, + cell.get("r")) + align = dict(item.get("align") or {}) + if "align_key" not in align and item.get("align_key"): + align["align_key"] = item["align_key"] + align["live_fingerprint"] = live_fingerprint(live_metric) + return {**dict(item), "fields": fields, "status": status, "align": align} + + +# ========================================================================== +# 抽取候选(真实现调模型;测试注入假的,不连真实业务库) +# ========================================================================== + + +async def extract_candidates(*, entries: list[dict[str, Any]], chunks: Mapping[str, Any], guidance: str, + datasource: Mapping[str, Any] | None, tables_text: str, fixed: str, + allowed_tables: set[str]) -> dict[str, Any]: + """把这次材料抽成候选 R:一次模型调用,交回 {metrics, visible_chunk_ids, prompt_version, parse_version, + model_id, problems, invisible…}。和起草主路径共用同一套提示词与校验(draftplan),只取定义,不用 SQL 建图。 + + 引用核对只认**实际进提示**的段落(fit_material 的结果):被截断丢掉的段落,模型引用它也核不上。 + """ + from app.ledger import draftplan + + fitted = draftplan.fit_material(entries, chunks, guidance, dict(datasource) if datasource else None, + tables_text, (), fixed) + async with SessionLocal() as session: + result = await draftplan.plan_groups(session, docs=entries, chunks=dict(chunks), guidance=guidance, + datasource=dict(datasource) if datasource else None, + tables_text=tables_text, covered=(), fixed=fixed, fitted=fitted) + visible = fitted[0] + metrics: list[dict[str, Any]] = [] + problems: list[dict[str, Any]] = [] + for raw in result.get("groups") or []: + plan, issues = draftplan.normalize_plan(raw, visible, allowed_tables=allowed_tables) + metrics.extend(plan.get("metrics") or []) + problems.extend(issues) + return {"metrics": metrics, "problems": problems, "visible_chunk_ids": list(result.get("visible_chunk_ids") or []), + "prompt_version": int(result.get("prompt_version") or 0), + "parse_version": int(result.get("parse_version") or 0), "model_id": str(result.get("model_id") or ""), + "sql_groups": list(result.get("groups") or [])} + + +async def _schema_material(session: Any, source: DataSource, focus_text: str) -> tuple[str, set[str]]: + from app.ledger.authoring import _schema_material as impl + + return await impl(session, source, focus_text) + + +# ========================================================================== +# 抽取主体:读材料 → 存来源快照 → 抽候选 → 算工作项 → 落库 +# ========================================================================== + + +async def _load_material(session: Any, draft: CaliberDraft) -> dict[str, Any]: + """读这次要导入的材料:草稿来源里的文档段落 + 数据源表结构。""" + origin = draft.origin if isinstance(draft.origin, dict) else {} + wanted = [str(d) for d in origin.get("documents") or []] + docs: list[Document] = [] + for doc_id in wanted: + doc = await session.get(Document, doc_id) + if doc is not None: + docs.append(doc) + chunks: dict[str, dict[str, Any]] = {} + entries: list[dict[str, Any]] = [] + for doc in docs: + rows = (await session.execute( + select(Chunk).where(Chunk.document_id == doc.id).order_by(Chunk.ordinal, Chunk.id))).scalars() + chunk_ids: list[str] = [] + for chunk in rows: + chunks[chunk.id] = {"ordinal": chunk.ordinal, "content": chunk.content or "", "document_id": doc.id} + chunk_ids.append(chunk.id) + entries.append({"document_id": doc.id, "title": doc.title or doc.source or doc.id, "chunk_ids": chunk_ids}) + source = await session.get(DataSource, draft.datasource_id) if draft.datasource_id else None + focus_text = "\n".join(str(c.get("content") or "") for c in chunks.values()) + tables_text, allowed = await _schema_material(session, source, focus_text) if source is not None else ("", set()) + documents = [{"document_id": doc.id, "title": doc.title or doc.source or doc.id, "source": doc.source or "", + "collection": doc.collection or "", "content": doc.content or ""} for doc in docs] + datasource = {"name": source.name, "type": source.kind, "description": source.description} if source else None + guidance = str(origin.get("guidance") or "") + fixed = str(origin.get("fixed_filters") or "") + return {"docs": documents, "chunks": chunks, "entries": entries, "datasource": datasource, + "tables_text": tables_text, "allowed_tables": allowed, "guidance": guidance, "fixed": fixed, + "source_row": source} + + +async def run_import(run_id: str) -> None: + """后台跑一次导入:读材料 → 存 R 的来源快照 → 抽候选 → 和 L / B 算工作项 → 落库。**不碰 L,也不碰 B。** + + 可重入:中途被打断之后再来一次,已经决定(接受/拒绝)的工作项保持决定,只重算还没定的。抽取只是候选, + 真正落到图上的是 accept(另一条路,见 accept_fields),所以重跑这里不会多建版本、也不会重复接受。 + """ + from app.core.artifact_store import put_json + from app.ledger import docdraft + + async with SessionLocal() as session: + run = await session.get(CaliberImportRun, run_id) + if run is None or run.status == "cancelled": + return + draft = await session.get(CaliberDraft, run.draft_id) + if draft is None: + run.status, run.error, run.finished_at = "failed", "草稿已删除", utcnow() + await session.commit() + return + workflow = await session.get(Workflow, run.workflow_id) if run.workflow_id else None + try: + material = await _load_material(session, draft) + except Exception as e: # noqa: BLE001 - 材料读不出来照实记失败,不留在「进行中」 + run.status, run.error, run.finished_at = "failed", f"读来源材料出错:{e}", utcnow() + await session.commit() + return + if not material["chunks"]: + run.status, run.error, run.finished_at = "failed", "这份草稿没有可导入的文档段落", utcnow() + await session.commit() + return + if not material["source_row"]: + run.status, run.error, run.finished_at = "failed", "没有数据源:抽取候选必须对照数据目录", utcnow() + await session.commit() + return + await session.commit() + + snapshot = docdraft.source_snapshot(documents=material["docs"], chunks=material["chunks"], + datasource=material["datasource"], catalog=material["tables_text"], + guidance=material["guidance"], fixed_filters=material["fixed"]) + try: + artifact_id = await put_json(snapshot, kind=docdraft.SNAPSHOT_KIND, node_id=run_id, + meta={"draft_id": draft.id, "import_run_id": run_id, + "source_snapshot_version": docdraft.SNAPSHOT_VERSION}) + ref = docdraft.snapshot_ref(artifact_id, snapshot) + except Exception: # noqa: BLE001 - 快照存不下:照实说没有可还原的 R 来源,不当成功 + ref = None + + async with SessionLocal() as session: + run = await session.get(CaliberImportRun, run_id) + if run is None or run.status == "cancelled": + return + run.source_snapshot = ref or {} + run.checkpoint = {**(run.checkpoint or {}), "stage": "extracting"} + await session.commit() + + try: + result = await extract_candidates(entries=material["entries"], chunks=material["chunks"], + guidance=material["guidance"], datasource=material["datasource"], + tables_text=material["tables_text"], fixed=material["fixed"], + allowed_tables=material["allowed_tables"]) + except Exception as e: # noqa: BLE001 - 抽取出错照实记,不假装完成 + async with SessionLocal() as session: + run = await session.get(CaliberImportRun, run_id) + if run is not None and run.status != "cancelled": + run.status, run.error, run.finished_at = "failed", f"抽取候选出错:{e}", utcnow() + await session.commit() + return + + candidates = list(result.get("metrics") or []) + visible = list(result.get("visible_chunk_ids") or []) + + async with SessionLocal() as session: + run = await session.get(CaliberImportRun, run_id) + if run is None or run.status == "cancelled": + return + draft = await session.get(CaliberDraft, run.draft_id) + workflow = await session.get(Workflow, run.workflow_id) if run.workflow_id else None + run.visible_chunk_ids = visible + run.prompt_version = int(result.get("prompt_version") or 0) + run.parse_version = int(result.get("parse_version") or 0) + run.model_id = result.get("model_id") or None + live_metrics = list(fieldbaseline.accepted_card(workflow.graph if workflow is not None else {})[1]) + ref = fieldbaseline.ref_of(draft.payload) if draft is not None else None + try: + baseline_values = fieldbaseline.values(ref) if ref else {} + except Exception: # noqa: BLE001 - B 读不回来当没有基线(baseline_unknown),不猜 + baseline_values = {} + built = build_items(candidates=candidates, live_metrics=live_metrics, + baseline_values=baseline_values, visible_chunk_ids=visible) + # 按**持久对齐键**认同一个工作项(不是候选位置 seq):顺序变了、条数变了都不会把接受 / 拒绝搬错项。 + # 对不上的候选是新的一项;老项(没有任何候选对上)原样留着,它自己的决定和依据一个字不动。 + by_key = {str(item.align_key): item for item in await _load_items(session, run_id) if item.align_key} + used_seq = {int(item.seq) for item in await _load_items(session, run_id)} + for made in built: + _upsert_item(session, run_id, made, by_key.get(made["align_key"]), live_metrics=live_metrics, + baseline_values=baseline_values, used_seq=used_seq) + await session.flush() + await _refresh_counts(session, run) + run.error = _problems_text(result.get("problems") or []) + run.status = "succeeded" if candidates else "failed" + if candidates and (result.get("problems") or run.error): + run.status = "partial" + if not candidates: + run.error = run.error or "模型没有交出可用的候选指标" + run.checkpoint = {**(run.checkpoint or {}), "stage": "aligned"} + run.finished_at = utcnow() + await session.commit() + + +def _problems_text(problems: Sequence[Mapping[str, Any]]) -> str: + return ";".join(f"{p.get('name') or '问题'}:{p.get('reason') or ''}".strip(":") + for p in problems if isinstance(p, Mapping) and p.get("reason"))[:2000] + + +async def _refresh_counts(session: Any, run: CaliberImportRun) -> None: + """重算读列表用的计数投影(工作项的处置状态变了就跟着变)。""" + rows = await _load_items(session, run.id) + run.items_total = len(rows) + run.items_decided = sum(1 for item in rows if item.status in ("accepted", "rejected", "unchanged")) + + +async def _load_items(session: Any, run_id: str) -> list[CaliberImportItem]: + return list((await session.execute(select(CaliberImportItem).where(CaliberImportItem.run_id == run_id) + .order_by(CaliberImportItem.seq))).scalars()) + + +def _alloc_seq(desired: int, used: set[int]) -> int: + """给一条新工作项挑一个还没被占的 seq:seq 只是显示顺序,(run_id, seq) 仍然唯一。 + + 对不上的旧行(迁移过来的、align_key 为空的)不参与匹配,所以新行不能直接沿用同一个 seq。 + """ + seq = int(desired) + if seq in used: + seq = (max(used) + 1) if used else 1 + while seq in used: + seq += 1 + used.add(seq) + return seq + + +def _upsert_item(session: Any, run_id: str, made: Mapping[str, Any], existing: CaliberImportItem | None, *, + live_metrics: Sequence[Mapping[str, Any]] = (), baseline_values: Mapping[str, Any] = {}, + used_seq: set[int] | None = None) -> None: + """把算好的工作项落库。 + + 已经有的行(按 align_key 对上的同一项)保留人的决定:接受的字段、拒绝的字段、applied_revision,以及 + **这一项自己的对齐依据**(对齐键、来源证据、可见段落)——新一轮重算不会把这些覆盖掉,只刷新三方和 + live_fingerprint 那个比较锚点。对不上的候选是新的一项(旧行原样留着)。 + """ + accepted = [str(p) for p in (existing.accepted or [])] if existing is not None else [] + rejected = [str(p) for p in (existing.rejected or [])] if existing is not None else [] + align = copy.deepcopy(dict(made["align"] or {})) + if existing is not None: + kept = dict(existing.align or {}) + for key in ("align_key", "evidence", "visible_chunk_ids", "invisible_citations", "identity_note", "manual"): + if key not in kept and key in align: + kept[key] = copy.deepcopy(align[key]) + kept["live_fingerprint"] = align.get("live_fingerprint") + align = kept + seed = {"fields": copy.deepcopy(dict(made["fields"])), "accepted": accepted, "rejected": rejected, + "align": align, "status": made.get("status"), "align_key": made.get("align_key")} + live = {str(m.get("id")): m for m in live_metrics if isinstance(m, Mapping)} + metric_id = str(made.get("metric_id") or "") + refreshed = refresh_item(seed, live_metric=live.get(metric_id), + baseline_values=(baseline_values or {}).get(metric_id) or {}, + baseline_known=bool(metric_id) and metric_id in (baseline_values or {})) + fields, status = refreshed["fields"], refreshed["status"] + row = existing + if row is None: + used = used_seq if used_seq is not None else set() + row = CaliberImportItem(run_id=run_id, seq=_alloc_seq(int(made["seq"]), used)) + session.add(row) + else: + if used_seq is not None: + used_seq.add(int(existing.seq)) + row.seq = int(existing.seq) + row.align_key = str(existing.align_key) if existing is not None and existing.align_key else \ + str(made.get("align_key") or align.get("align_key") or "") + row.metric_id, row.candidate_id, row.name = made["metric_id"], made["candidate_id"], made["name"] + row.align, row.fields = align, fields + row.accepted, row.rejected = accepted, rejected + row.status = status + if not (accepted or rejected): + row.error = made.get("error") or None + + +# ========================================================================== +# 工作项定位:按 item.id(首选);旧调用只给 metric_id 时要求唯一 +# ========================================================================== + + +async def resolve_item(session: Any, run: CaliberImportRun, spec: Mapping[str, Any]) -> CaliberImportItem: + """一次选择指向哪条工作项:**首选 item_id**(工作项的稳定主键)。 + + 旧调用只给 metric_id(或未对齐项的 seq)时: + - metric_id 只在这条导入里**唯一**对得上一条工作项时才认;对上不止一条(重复 metric 候选、或两条候选对到 + 同一条指标)回 409,把候选的 item_id 列出来让人指明——绝**不取最后一条**; + - seq 只当旧客户端的兜底(位置本身不稳定,新调用别用)。 + """ + spec = spec or {} + item_id = str(spec.get("item_id") or "").strip() + if item_id: + item = await session.get(CaliberImportItem, item_id) + if item is None or item.run_id != run.id: + raise ImportRefused(404, "这条工作项不存在(可能这次导入已经重建过):请刷新后再试", + IMPORT_ITEM_UNKNOWN) + return item + metric_id = str(spec.get("metric_id") or "").strip() + items = await _load_items(session, run.id) + if metric_id: + matched = [item for item in items if str(item.metric_id) == metric_id] + if len(matched) == 1: + return matched[0] + if len(matched) > 1: + ids = "、".join(str(item.id) for item in matched) + raise ImportRefused(409, f"指标「{metric_id}」在这次导入里对上了不止一条工作项({ids}):" + f"请按 item_id 指明是哪一条,别按指标名猜", IMPORT_ITEM_AMBIGUOUS, + extra={"item_ids": [str(item.id) for item in matched]}) + raise ImportRefused(409, f"这次导入里没有对齐到指标「{metric_id}」的工作项,请刷新后再试", + IMPORT_ITEM_UNKNOWN) + if spec.get("seq") is not None: + for item in items: + if int(item.seq) == int(spec.get("seq")): + return item + raise ImportRefused(409, "这次导入里没有对得上的工作项(给 item_id,或唯一对得上一条的 metric_id)", + IMPORT_ITEM_UNKNOWN) + + +# ========================================================================== +# 显式恢复未完成的工作项 +# ========================================================================== + + +async def unfinished(session: Any, run_id: str) -> list[CaliberImportItem]: + """这次导入里还没做完的工作项:抽取失败、或有还没决定的格子。 + + 「还没做完」不含已经接受 / 拒绝完了的:恢复不会去动人的决定,也不会重复接受、重复建版。 + """ + return [item for item in await _load_items(session, run_id) + if item.status not in ("accepted", "rejected", "unchanged")] + + +async def reject_fields(session: Any, *, run: CaliberImportRun, selections: Sequence[Mapping[str, Any]], + note: str | None = None) -> int: + """拒绝选定的字段(或整条工作项):保持 L 不动、也不推进 B。 + + 定位按 item_id(旧调用给 metric_id 时要唯一对得上一条,见 resolve_item)。`fields` 为空表示整条都拒 + (还没决定的格子全拒)。已经接受过的格子不动——拒绝不改已经落到图上的事。 + """ + touched = 0 + for spec in selections: + item = await resolve_item(session, run, spec or {}) + fields = dict(item.fields or {}) + paths = [str(p) for p in ((spec or {}).get("fields") or [])] or [ + path for path, cell in fields.items() + if isinstance(cell, Mapping) and cell.get("decided") != "accepted"] + for path in paths: + cell = fields.get(path) + if not isinstance(cell, Mapping): + raise ImportRefused(422, f"工作项「{item.name or item.metric_id}」上没有字段 {path}", + IMPORT_FIELD_UNKNOWN, extra={"path": path}) + if cell.get("decided") == "accepted": + continue + cell = dict(cell) + cell["decided"] = "rejected" + fields[path] = cell + if path not in (item.rejected or []): + item.rejected = sorted({*(item.rejected or []), path}) + item.fields = fields + item.status = item_status(mode=str((item.align or {}).get("mode") or "new"), fields=fields, + accepted=item.accepted or [], rejected=item.rejected or [], + failed=item.status == "failed") + if note: + item.error = str(note)[:500] + touched += 1 + await _refresh_counts(session, run) + await session.commit() + return touched + + +async def realign_item(session: Any, *, run: CaliberImportRun, draft: CaliberDraft, workflow: Workflow, + item: CaliberImportItem, metric_id: str) -> None: + """人工把一条工作项对到当前图的某条指标上(或 `metric_id=""` 取消对齐)。 + + 「baseline_unknown 必须人工对齐」和「同名不同范围要人来定」都走这里:R 的值原样留着,换一个 L 一格、重算三方。 + 人一旦重新对齐,旧的接受 / 拒绝决定不再适用(换了对哪一条,决定就换了对象),清空重来。 + """ + live_metrics = list(fieldbaseline.accepted_card(workflow.graph if workflow is not None else {})[1]) + live_by_id = {str(m.get("id")): m for m in live_metrics if isinstance(m, Mapping) and m.get("id")} + metric_id = str(metric_id or "").strip() + if metric_id and metric_id not in live_by_id: + raise ImportRefused(409, f"图上没有指标「{metric_id}」:先刷新页面看现在的口径卡", IMPORT_ITEM_UNKNOWN) + ref = fieldbaseline.ref_of(draft.payload) + try: + baseline_values = fieldbaseline.values(ref) if ref else {} + except Exception: # noqa: BLE001 - B 读不回来当没有基线 + baseline_values = {} + baseline_known = bool(metric_id) and metric_id in baseline_values + fields: dict[str, Any] = {} + for path, cell in (item.fields or {}).items(): + if not isinstance(cell, Mapping): + continue + candidate = cell.get("r") if cell.get("r_present") else _MISSING + live = _live_value(live_by_id.get(metric_id), path) + base = _baseline_value(baseline_values.get(metric_id) or {}, path) + fields[path] = {**dict(cell), + "state": field_state(baseline=base, live=live, candidate=candidate, + baseline_known=baseline_known), + "b": None if base is _MISSING else copy.deepcopy(base), + "b_present": base is not _MISSING, + "l": None if live is _MISSING else copy.deepcopy(live), + "l_present": live is not _MISSING, + "decided": None} + align_info = dict(item.align or {}) + # 人工对齐之后:对齐键跟着新的稳定身份走(下次恢复按它对得上);模式按「对上了哪一条」记, + # 不再按 baseline 有没有来定——没有基线时逐格的 state 本来就是 manual,不必让整条卡在 manual 上。 + align_info.update({"mode": "evidence" if metric_id else "new", "manual": True, "metric_id": metric_id, + "reason": "人工对齐" if metric_id else "人工取消对齐(当作新指标)"}) + align_info["align_key"] = alignment_key(metric_id=metric_id, + evidence=align_info.get("evidence") or []) + align_info["live_fingerprint"] = live_fingerprint(live_by_id.get(metric_id)) + for path, cell in fields.items(): + if isinstance(cell, dict): + cell["acceptable"] = _acceptable( + "failed" if item.status == "failed" else "manual", cell.get("state"), + bool(cell.get("r_present")), path, cell.get("r")) + item.metric_id, item.align, item.align_key = metric_id, align_info, align_info["align_key"] + item.fields, item.accepted, item.rejected = fields, [], [] + item.status = item_status(mode=align_info["mode"], fields=fields, accepted=[], rejected=[], + failed=item.status == "failed") + for path, cell in item.fields.items(): + if isinstance(cell, dict): + cell["acceptable"] = _acceptable(item.status, cell.get("state"), bool(cell.get("r_present")), path, + cell.get("r")) + await _refresh_counts(session, run) + await session.commit() + + +# ========================================================================== +# 接受选定字段:原子落库(先写不可变的新 B 工件,再一个事务提交 L + 工作项决定 + 新 B 引用) +# ========================================================================== + + +async def accept_fields(session: Any, *, run: CaliberImportRun, draft: CaliberDraft, workflow: Workflow, + card_id: str, selections: Sequence[Mapping[str, Any]], actor: str | None, + request_id: str | None, expected_revision: int | None) -> dict[str, Any]: + """接受选定的字段:**一次性**落到 L(新增一版图),并按被接受的那几格推进 B。 + + 顺序是刻意的(原子性,也是这次修复的要点): + + 1. 校验 + 幂等:同 request_id 的重放直接交回上一次已提交的结果,不重写; + 2. 在**图的深拷贝**上把整批改完(K03 的白名单字段走 changes.apply_operations,引用原文按同一份图一起写), + 拿到新图和它对应的版本号——**这时还不写库**; + 3. 先把推进后的**不可变 B 工件写出来**。工件写失败就让整次接受失败,L 一个字节都不落(不会出现「L 提交了、 + B 永远没推进」:重试幂等回放却发现 B 缺失)。万一后面的事务回滚,留下的是一个**孤儿工件**——内容寻址的 + 不可变工件,没有任何引用指向它,可以接受; + 4. **同一个数据库事务**里提交 L 的新版本(save_graph 的 CAS / 版本语义)、工作项的决定、草稿 payload 上的 + 新 B 引用与历史,以及写入幂等键。任一步失败一起回滚,新 L 不可见; + 5. 提交之后只做读侧的重算(刷新工作项的三方),不再写库。 + + 于是「L 新增一版」和「B 往前推一格」是同一次提交里的事:重放交回已提交的结果、B 读得回来;同键不同内容仍旧冲突。 + """ + from app.apps.versions import (WRITE_CONFLICT, WRITE_REPLAY, WorkflowChanged, claim_write, remember_write, + save_graph, write_fingerprint) + from app.ledger import changes + from app.ledger.repository import CaliberGone + + requested: list[tuple[CaliberImportItem, str]] = [] + for spec in selections: + item = await resolve_item(session, run, spec or {}) + fields = item.fields if isinstance(item.fields, dict) else {} + explicit = [str(p) for p in ((spec or {}).get("fields") or [])] + auto = bool((spec or {}).get("auto")) + if item.status == "failed": + # 整条失败(引用一段都没核对上):任何一格都不能接受——尤其不能用空的 R 把 citations 清掉 + if explicit: + raise ImportRefused(422, f"这条候选没有一条引用能核对上({item.error or '抽取失败'}):" + f"整条不可接受,请重新抽取或人工补依据", IMPORT_ITEM_FAILED, + extra={"item_id": str(item.id)}) + continue # auto:整条跳过去,不选任何一格 + if not str(item.metric_id or ""): + raise ImportRefused(409, f"工作项「{item.name or item.candidate_id or item.id}」还没对齐到图上的指标:" + f"先在这次导入里人工对齐,再接受", IMPORT_ITEM_UNALIGNED, + extra={"item_id": str(item.id)}) + if explicit: + paths = explicit + elif auto: + # auto **只**收还没决定的「无冲突更新 + 新增候选」:已接受 / 已拒绝的一律跳过 + # (重放请把明确字段一起带上,前端就是这么发的) + paths = [str(path) for path, cell in fields.items() + if isinstance(cell, Mapping) and cell.get("decided") is None + and cell.get("state") in ("update", "new")] + else: + paths = [] + for path in paths: + if path not in fields: + raise ImportRefused(422, f"工作项「{item.name or item.metric_id}」上没有字段 {path}", + IMPORT_FIELD_UNKNOWN, + extra={"item_id": str(item.id), "metric_id": item.metric_id, "path": path}) + requested.append((item, path)) + if not requested: + raise ImportRefused(422, "没有选中任何可以接受的字段", IMPORT_NOTHING_SELECTED) + + workflow_id = str(workflow.id) + fingerprint = write_fingerprint(sorted([{"item_id": str(item.id), "path": path} + for item, path in requested], key=lambda x: (x["item_id"], x["path"]))) + claim = await claim_write(session, actor=actor, workflow_id=workflow_id, target=card_id, + request_id=request_id, payload_hash=fingerprint) + if claim.state == WRITE_CONFLICT: + raise ImportRefused(409, "同一个 request_id 已经用不同的内容提交过:请换一个 request_id 再提交", + IMPORT_IDEMPOTENCY_CONFLICT, extra={"current_version": workflow.version}) + if claim.state == WRITE_REPLAY: + # 上一次已经整批提交过(L 那一版和 B 那一件是同一次提交):交回那一次的结果,B 读得回来 + return {"applied": False, "replayed": True, + "revision": claim.revision if isinstance(claim.revision, int) else workflow.version} + + picked: list[tuple[CaliberImportItem, str, Any]] = [] + for item, path in requested: + cell = (item.fields or {}).get(path) + if not isinstance(cell, Mapping): + raise ImportRefused(422, f"工作项「{item.name or item.metric_id}」上没有字段 {path}", + IMPORT_FIELD_UNKNOWN, extra={"item_id": str(item.id), "path": path}) + if item.status == "failed": + raise ImportRefused(422, f"这条候选没有一条引用能核对上({item.error or '抽取失败'}):" + f"整条不可接受,请重新抽取或人工补依据", IMPORT_ITEM_FAILED, + extra={"item_id": str(item.id)}) + if cell.get("decided") == "accepted": + continue # 已经接受过这一格,幂等 + state = cell.get("state") + value = cell.get("r") + if not cell.get("r_present") or state not in ACCEPT_STATES: + raise ImportRefused(422, _not_acceptable_message(str(item.metric_id), path, state), + IMPORT_FIELD_NOT_ACCEPTABLE, + extra={"item_id": str(item.id), "metric_id": item.metric_id, "path": path, + "state": state}) + if path == fieldbaseline.CITATIONS_FIELD and not value: + # 出处不能被接受成空:那等于把这条定义的证据删掉 + raise ImportRefused(422, f"{path} 不能接受成空的:出处是这条定义的依据,不接受就把这一格留着", + IMPORT_FIELD_NOT_ACCEPTABLE, + extra={"item_id": str(item.id), "metric_id": item.metric_id, "path": path}) + picked.append((item, path, value)) + if not picked: + raise ImportRefused(422, "没有选中任何可以接受的字段", IMPORT_NOTHING_SELECTED) + + if expected_revision is None: + raise ImportRefused(409, f"这次导入要落到工作流上(现在是 v{workflow.version}):" + f"接受要带上读到的版本(expected_revision),请刷新页面后再改", + IMPORT_REVISION_REQUIRED, extra={"current_version": workflow.version}) + # 候选算出来之后 L 被人改过就不落:客户端只把 expected_revision 更新到最新一版也不行—— + # 三方要按现在的 L 重新算、人重新确认(刷新这次导入的三方,或重新抽一次)。 + stale = _stale_l_items(picked, workflow.graph if isinstance(workflow.graph, dict) else {}, + fieldbaseline.accepted_card(workflow.graph if isinstance(workflow.graph, dict) else {})[1]) + if stale: + names = "、".join(f"{item.name or item.metric_id}({path})" for item, path in stale) + raise ImportRefused(409, f"这几格的当前内容和这次导入算候选时的那一版不一样了:{names}。" + f"请刷新这次导入的三方、按现在的口径重新确认后再接受", + IMPORT_STALE_L, extra={"fields": [{"item_id": str(item.id), + "metric_id": item.metric_id, "path": path} + for item, path in stale]}) + if expected_revision != workflow.version: + raise ImportRefused(409, f"口径已经改到 v{workflow.version},你的版本是 v{expected_revision}:" + f"请刷新后重新核对再接受", IMPORT_STALE_REVISION, + extra={"current_version": workflow.version}) + + # 同一条指标的同一位被两项候选各带一份说法:不能「取最后一条」——请人分开接受 + seen: dict[tuple[str, str], Any] = {} + for item, path, value in picked: + key = (str(item.metric_id), path) + if key in seen and seen[key] != value: + raise ImportRefused(409, f"这次接受给指标「{key[0]}」的 {path} 带来了两份不一样的说法:" + f"请按 item_id 分开接受", IMPORT_ITEM_AMBIGUOUS, + extra={"metric_id": key[0], "path": path}) + seen[key] = value + + whitelist = [(item.metric_id, path, value) for item, path, value in picked if path in changes.FIELDS] + citations = {item.metric_id: value for item, path, value in picked if path == fieldbaseline.CITATIONS_FIELD} + for metric_id, path, _value in picked: + if path in changes.FIELDS or path == fieldbaseline.CITATIONS_FIELD: + continue + raise ImportRefused(422, f"字段 {path} 不在接受的范围内", IMPORT_FIELD_NOT_ACCEPTABLE, + extra={"metric_id": metric_id, "path": path}) + # 2) 先在拷贝上把整批改完(不落库) + try: + change = changes.apply_operations(workflow.graph or {}, card_id=card_id, operations=[ + {"op": "set", "metric_id": metric_id, "path": path, "value": copy.deepcopy(value)} + for metric_id, path, value in whitelist]) if whitelist else None + except changes.ChangeRefused as e: + raise ImportRefused(422, e.message, e.code, extra={"operation": e.operation, "path": e.path}) from None + except CaliberGone: + raise _card_gone(workflow.version) from None + graph = change.graph if change is not None else copy.deepcopy(workflow.graph or {}) + if citations: + graph = _set_citations(graph, card_id, citations) + + # 3) 先写不可变的新 B 工件(孤儿可接受):写不出来就让整次接受失败,L 不提交 + new_ref = await _write_advanced_baseline(run=run, draft=draft, workflow=workflow, card_id=card_id, + graph=graph, picked=picked, actor=actor) + + # 4) 一个事务:L 的新版本 + 工作项的决定 + 草稿上的新 B 引用/历史(+ 幂等键) + # 回滚之后 ORM 对象会被 expire,异常分支里不再读它们的属性(current_version 提前取好)。 + current_version = int(workflow.version) + try: + await save_graph(session, workflow, graph, note="接受增量导入", expected_revision=expected_revision) + for item, path, _value in picked: + item.accepted = sorted({*(item.accepted or []), path}) + item.rejected = [p for p in (item.rejected or []) if p != path] + item.applied_revision = workflow.version + run.checkpoint = {**(run.checkpoint or {}), + "accepted": sorted({f"{item.metric_id}{path}" for item, path, _ in picked})} + history = fieldbaseline.history(draft.payload) + draft.payload = {**(draft.payload if isinstance(draft.payload, dict) else {}), + fieldbaseline.REF_KEY: new_ref, + fieldbaseline.HISTORY_KEY: [*history, new_ref]} + await remember_write(session, actor=actor, workflow_id=workflow_id, target=card_id, + request_id=request_id, payload_hash=fingerprint, revision=workflow.version) + await _refresh_run_items(session, run=run, draft=draft, workflow=workflow) + await session.commit() + except WorkflowChanged as e: + await session.rollback() + raise ImportRefused(409, str(e), IMPORT_STALE_REVISION, + extra={"current_version": getattr(e, "current", current_version)}) from None + except IntegrityError: + # 两路真并发带同一个 request_id:后到的那一路撞唯一键,回滚掉自己写的图,按赢的那一路当重放交回。 + # 只有重查确认是同一件事(同键同内容)才当重放;记录还不存在照旧抛出去。 + await session.rollback() + if not request_id: + raise + claim = await claim_write(session, actor=actor, workflow_id=workflow_id, target=card_id, + request_id=request_id, payload_hash=fingerprint) + if claim.state == WRITE_CONFLICT: + raise ImportRefused(409, "同一个 request_id 已经用不同的内容提交过:请换一个 request_id 再提交", + IMPORT_IDEMPOTENCY_CONFLICT) from None + if claim.state != WRITE_REPLAY: + raise + current = await session.scalar(select(Workflow.version).where(Workflow.id == workflow_id)) + return {"applied": False, "replayed": True, + "revision": claim.revision if isinstance(claim.revision, int) else (int(current) if current else None)} + # 5) 读侧的重算已经在同一个事务里做完了(刷新工作项的三方),这里不再写库 + return {"applied": True, "replayed": False, "revision": workflow.version} + + +def _card_metrics(graph: Mapping[str, Any] | None, card_id: str) -> list[dict[str, Any]]: + """卡上的指标(接受之后的那一份):coverage 的 expected 和 uncovered 都按它算。""" + for node in (graph or {}).get("nodes") or []: + if not isinstance(node, Mapping) or str(node.get("id")) != card_id: + continue + data = node.get("data") + config = data.get("config") if isinstance(data, Mapping) else None + config = config if isinstance(config, Mapping) else {} + return [dict(m) for m in config.get("metrics") or [] if isinstance(m, Mapping) and m.get("id")] + return [] + + +def _next_revision(current: int, graph: Any, old_graph: Any) -> int: + """这次接受会落在哪一版:内容真变了才新增一版(和 save_graph 的判定同一套)。""" + return int(current) + (1 if graph != (old_graph or {}) else 0) + + +async def _write_advanced_baseline(*, run: CaliberImportRun, draft: CaliberDraft, workflow: Workflow, + card_id: str, graph: dict[str, Any], + picked: Sequence[tuple[Any, str, Any]], actor: str | None) -> dict[str, Any]: + """先写推进后的不可变 B 工件(不改库、不动 L);写不出来抛 503,让这次接受整体失败。 + + 只并进这次被接受的格子;expected_fields 取**接受之后**卡上那条指标声明的字段路径,card_metric_ids 取卡上 + 全部指标——coverage 据此判 partial(没覆盖到的格、整条没有基线的指标都记下来)。 + """ + updates: dict[str, dict[str, Any]] = {} + for item, path, value in picked: + entry = updates.setdefault(str(item.metric_id), {"name": item.name, "fields": {}, "expected_fields": []}) + entry["fields"][path] = copy.deepcopy(value) + card_metrics = _card_metrics(graph, card_id) + by_id = {str(m.get("id")): m for m in card_metrics} + for metric_id, entry in updates.items(): + entry["expected_fields"] = sorted(fieldbaseline.fields_of(by_id.get(metric_id) or {})) + made = await fieldbaseline.advance( + ref=fieldbaseline.ref_of(draft.payload), updates=updates, card_id=card_id, workflow_id=workflow.id, + accepted_revision=_next_revision(workflow.version, graph, workflow.graph), draft_id=draft.id, + source_snapshot=run.source_snapshot or None, accepted_by=actor, + card_metric_ids=[str(m.get("id")) for m in card_metrics]) + if made is None: + raise ImportRefused(503, "字段基线工件写不进去:这次接受没有落库(L 未提交),请稍后重试", + IMPORT_BASELINE_UNAVAILABLE) + return made + + +def _card_gone(revision: int | None) -> "ImportRefused": + return ImportRefused(409, "这张口径卡不见了(可能刚被删掉或改成转抄卡):请刷新页面再看一次", + IMPORT_ITEM_UNKNOWN, extra={"current_version": revision}) + + +def _stale_l_items(picked: Sequence[tuple[Any, str, Any]], graph: Mapping[str, Any], + live_metrics: Sequence[Mapping[str, Any]]) -> list[tuple[Any, str]]: + """这次要接受的格子:候选算出来时记下的 L 指纹和现在图上的对不对得上。 + + 对不上的返回(工作项, 路径):→ 接口回 409 import_stale_l,要人刷新三方重新确认,不能只更新 expected_revision 覆盖。 + """ + live = {str(m.get("id")): m for m in live_metrics if isinstance(m, Mapping) and m.get("id")} + stale: list[tuple[Any, str]] = [] + for item, path, _value in picked: + anchor = str((item.align or {}).get("live_fingerprint") or "") + if not anchor: + continue # 老工作项没有这个锚点:不拿它判(宁可不拦,也不误拦) + if live_fingerprint(live.get(str(item.metric_id or ""))) != anchor: + stale.append((item, path)) + return stale + + +def _not_acceptable_message(metric_id: str, path: str, state: Any) -> str: + if state == "missing": + return f"字段 {path} 这次没有提取到(漏提取不当删除):不能接受,L 上原来的值原样留着" + if state == "unchanged": + return f"字段 {path} 和现在的内容一致:不用接受" + return f"字段 {path} 现在的状态是「{state}」,不能接受" + + +def _set_citations(graph: dict[str, Any], card_id: str, citations: Mapping[str, Any]) -> dict[str, Any]: + """把接受的引用原文写进口径卡上的指标(同一次 save_graph:只新增一版,不覆盖旧版本)。 + + 卡上没有这条指标时不静默丢掉:对齐之后目标指标必须还在图上,不在了就是这次接受落不下去。 + """ + seen: set[str] = set() + for node in graph.get("nodes") or []: + if not isinstance(node, dict) or str(node.get("id")) != card_id: + continue + config = (node.get("data") or {}).get("config") if isinstance(node.get("data"), Mapping) else None + config = config if isinstance(config, dict) else {} + for metric in config.get("metrics") or []: + if not isinstance(metric, dict) or str(metric.get("id")) not in citations: + continue + metric_id = str(metric["id"]) + definition = metric.get("definition") + definition = dict(definition) if isinstance(definition, dict) else {} + definition["citations"] = copy.deepcopy(citations[metric_id]) + metric["definition"] = definition + seen.add(metric_id) + missing = sorted(set(str(mid) for mid in citations) - seen) + if missing: + raise ImportRefused(409, f"这张口径卡上找不到要写引用的指标:{'、'.join(missing)},请刷新后再试", + IMPORT_ITEM_UNKNOWN, extra={"metric_ids": missing}) + return graph + + +async def _refresh_run_items(session: Any, *, run: CaliberImportRun, draft: CaliberDraft, + workflow: Workflow) -> None: + """L / B 动过之后,把这次导入还没决定的格子重算一遍(已接受的保持接受、没对齐的不动)。 + + 没对齐上的工作项(mode 是 new / manual、metric_id 为空)没有可比的 L 一格,保持抽出来时的样子: + 要对齐得先走人工对齐(reimport.align 的入口在接口层)。 + """ + from app.api.ledger import _draft_graph_payload + + live_metrics = list(fieldbaseline.accepted_card(workflow.graph if workflow is not None else {})[1]) + live_by_id = {str(m.get("id")): m for m in live_metrics if isinstance(m, Mapping)} + ref = fieldbaseline.ref_of(draft.payload) + try: + baseline_values = fieldbaseline.values(ref) if ref else {} + except Exception: # noqa: BLE001 - B 读不回来当没有基线 + baseline_values = {} + for item in await _load_items(session, run.id): + if not item.metric_id: + continue + merged = refresh_item({"fields": item.fields, "accepted": item.accepted, "rejected": item.rejected, + "align": item.align, "status": item.status}, + live_metric=live_by_id.get(str(item.metric_id)), + baseline_values=(baseline_values.get(str(item.metric_id)) or {}), + baseline_known=str(item.metric_id) in baseline_values) + item.fields, item.status, item.align = merged["fields"], merged["status"], merged["align"] + await _refresh_counts(session, run) + if workflow is not None: + live = await _draft_graph_payload(session, workflow, workflow.version) + if live is not None: + draft.payload = {**(draft.payload or {}), **live} + + +# ========================================================================== +# 后台任务载体(core/job_runtime:重启标中断、不自动续跑、能显式恢复) +# ========================================================================== + + +class ImportJob(runtime.JobRun): + model = CaliberImportRun + kind = "caliber_import" + + def lane_of(self, job: Any) -> None: + """抽候选只读文档和表结构、调模型,不查业务库:不占数据源的队,直接跑。""" + return None + + async def _run(self) -> None: + if not await self._write(runtime.claim, CaliberImportRun, self.job_id): + return + await run_import(self.job_id) + + async def _stopped(self) -> None: + interrupted = self.stop_reason != "user" + await self._write(_finish, self.job_id, "interrupted" if interrupted else "cancelled", + "服务中断,已保留导入进度,可恢复" if interrupted else "导入已停止,已保留进度") + + async def _failed(self, reason: str) -> None: + await self._write(_finish, self.job_id, "failed", reason) + + async def _crashed(self, exc: Exception) -> None: + await self._write(_finish, self.job_id, "failed", f"增量导入失败:{exc}") + + +async def _finish(session: Any, run_id: str, status: str, error: str | None) -> None: + run = await session.get(CaliberImportRun, run_id) + if run is None or run.status in ("cancelled",): + return + run.status, run.error, run.finished_at = status, error, utcnow() + await session.commit() + + +manager = runtime.JobManager(ImportJob, label="口径增量导入", name="caliber_import") + + +async def start(run_id: str) -> None: + manager.start(run_id) + + +async def startup(*, live: Any = None) -> int: + """服务启动时接手属主不在了的导入:记 interrupted、保留工作项,等人点「恢复」再续(不自动续跑)。""" + async def close(session: Any, job_id: str) -> None: + await _finish(session, job_id, "interrupted", "服务中断,已保留导入进度,可恢复") + + return await runtime.interrupt_on_startup(CaliberImportRun, close, running=manager.running, live=live) + + +async def resume(session: Any, run: CaliberImportRun) -> dict[str, Any]: + """显式恢复:把这次导入重新排进后台,续做还没完成的工作项(已接受 / 拒绝的不动,不重复建版)。 + + 工作项按**持久对齐键**认(稳定 metric 身份 + 规范化来源证据),不按候选位置:顺序变了、条数变了都不会串项。 + """ + if run.status in ("queued", "running"): + where = "正在运行" if run.status == "running" else "排队中" + raise ImportRefused(409, f"这次导入{where}(状态:{run.status}):请等它结束再恢复," + f"期间不用重复点", IMPORT_ALREADY_RUNNING, extra={"status": run.status}) + pending = await unfinished(session, run.id) + if run.items_total and not pending: + raise ImportRefused(409, "这次导入没有未完成的工作项", IMPORT_NOTHING_TO_RESUME) + run.status, run.error, run.finished_at = "queued", None, None + run.checkpoint = {**(run.checkpoint or {}), "resumed": True} + await session.commit() + await start(run.id) + return {"run_id": run.id, "status": "queued"} + + +async def refresh(session: Any, *, run: CaliberImportRun, draft: CaliberDraft, workflow: Workflow) -> None: + """按**现在的** L / B 重算这次导入还没决定的三方,并刷新每项的 live_fingerprint 比较锚点。 + + 这是 import_stale_l 之后的恢复动作:工件项、接受 / 拒绝的决定、每项自己的来源依据都不动,只重算三方; + 人看过新三方、重新确认,再接受。 + """ + await _refresh_run_items(session, run=run, draft=draft, workflow=workflow) + run.checkpoint = {**(run.checkpoint or {}), "refreshed": True} + await session.commit() + + +__all__ = ["ACCEPT_STATES", "FIELD_STATES", "ITEM_STATUSES", "RUN_STATUSES", "ImportJob", "ImportRefused", + "accept_fields", "align", "alignment_key", "build_item", "build_items", "citation_chunks", + "extract_candidates", "field_state", "item_status", "live_fingerprint", "manager", "realign_item", + "refresh", "refresh_item", "reject_fields", "resolve_item", "resume", "run_import", "start", + "startup", "unfinished", "visible_citations"] diff --git a/backend/app/ledger/repository.py b/backend/app/ledger/repository.py new file mode 100644 index 00000000..c0d66c06 --- /dev/null +++ b/backend/app/ledger/repository.py @@ -0,0 +1,153 @@ +"""口径的领域边界(K03、A01):一份口径卡按卡和指标说话,不说节点、data.config 和路径。 + +图仍是唯一真相(A01:每份口径只有一个权威写入源)。GraphBackedCaliberRepository 在图上给一层很薄的领域接口: +按卡 id 打开一张源头口径卡、按稳定 metric_id 读一条指标、把改过的这几条换回去——换在**整图的深拷贝**上, +没提到的字段、别的指标、别人加的扩展字段和其他节点原样带着走。这里不做整图 ↔ 领域模型的双向转换,也不另存一份 +可编辑的定义:那就是第二份真相,A01 明令禁止。 + +只认源头口径卡:转抄别处的口径卡(caliber_from,ledger/compose 内联实例化出来的那些)不是权威写入源,改它等于 +在别处另存一份定义。指标的完整身份是「卡 + 卡上的 metric_id」(4.1),所以这里所有读写都同时带着这两个。 + +定义指纹用现成的 data/caliber_identity(只按语义字段算,空值不进哈希):变更服务据此说「这次动没动定义」, +不另造一套指纹。 +""" +from __future__ import annotations + +import copy +from collections.abc import Mapping +from dataclasses import dataclass +from typing import Any + + +class CaliberGone(ValueError): + """图里没有这张可写的口径卡:不在图上、不是口径卡节点,或者是转抄别处的口径卡(不是权威写入源)。""" + + +class MetricGone(LookupError): + """这张口径卡上没有这个 metric_id。""" + + +@dataclass(frozen=True) +class CaliberCard: + """一张源头口径卡的身份:图上的节点 id、给人看的标题、口径名和口径版本。""" + + node_id: str + title: str + caliber: str + caliber_version: str + + +def _config_of(node: Any) -> dict[str, Any]: + """节点上的配置(图的原始形状 data.config);没有或者不是对象时交回空的那一份(读的时候不改图)。""" + data = node.get("data") if isinstance(node, Mapping) else None + config = data.get("config") if isinstance(data, Mapping) else None + return config if isinstance(config, dict) else {} + + +class GraphBackedCaliberRepository: + """一张源头口径卡在图上的一层薄领域接口。构造时就把卡定位好,定位不到直接 CaliberGone。""" + + def __init__(self, graph: Mapping[str, Any] | None, *, card_id: str) -> None: + self._graph = graph if isinstance(graph, dict) else {} + self.card_id = str(card_id or "") + self._node = self._card_node() + + def _card_node(self) -> dict[str, Any]: + for node in self._graph.get("nodes") or []: + if not isinstance(node, dict) or str(node.get("id")) != self.card_id: + continue + if node.get("type") != "metrics": + raise CaliberGone(f"图上这个节点不是口径卡:{self.card_id}") + if _config_of(node).get("caliber_from") not in (None, "", {}): + raise CaliberGone("这张卡是从别处转抄来的口径:要改的是它抄的那一份") + return node + raise CaliberGone(f"图上没有这张口径卡:{self.card_id}") + + @property + def card(self) -> CaliberCard: + data = self._node.get("data") if isinstance(self._node.get("data"), dict) else {} + config = _config_of(self._node) + return CaliberCard(node_id=self.card_id, title=str(data.get("label") or self.card_id), + caliber=str(config.get("caliber") or ""), + caliber_version=str(config.get("caliber_version") or "")) + + def ids(self) -> list[str]: + """卡上的 metric_id,按它们在图里的先后(重排只改顺序,不改 ID)。没有 id 的条目(画布上留下的半成品)跳过。""" + return [str(metric["id"]) for metric in self._metrics() + if isinstance(metric, dict) and str(metric.get("id") or "").strip()] + + def metrics(self) -> list[dict[str, Any]]: + """卡上每条指标的深拷贝(顺序照图里)。""" + return [copy.deepcopy(metric) for metric in self._metrics()] + + def metric(self, metric_id: str) -> dict[str, Any]: + """一条指标的深拷贝;卡上没有它时 MetricGone。调用方随便改这一份,图不动。""" + wanted = str(metric_id or "") + for metric in self._metrics(): + if isinstance(metric, dict) and str(metric.get("id") or "") == wanted: + return copy.deepcopy(metric) + raise MetricGone(wanted) + + def graph_copy(self) -> dict[str, Any]: + """整图的深拷贝:调用方(变更服务)把改过的那一份交回去保存,原图不动。""" + return copy.deepcopy(self._graph) + + def replace_node_configs(self, configs: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]: + """换掉图上这几个取数节点的 data.config(node_id → 整份新配置),交回整图的深拷贝。 + + K04 的绑定同步用:调用方(ledger/bindings.plan)给的新配置是在**原配置的深拷贝**上只改两处得来的, + 所以节点上别的键(tool、args 里别的项、扩展字段)、别的地方一个字不动。指到图里没有的节点时 KeyError—— + 这是服务端的 bug,照实抛出去,不当成一次成功的同步。 + """ + graph = copy.deepcopy(self._graph) + nodes = {str(node.get("id")): node for node in graph.get("nodes") or [] if isinstance(node, dict)} + for node_id, config in configs.items(): + node = nodes.get(str(node_id)) + if node is None: + raise KeyError(f"图上没有这个节点:{node_id}") + data = node.get("data") + if not isinstance(data, dict): + data = node["data"] = {} + data["config"] = copy.deepcopy(dict(config)) + return graph + + def replace_metrics(self, metrics: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]: + """换掉 map 里这几条指标(metric_id → 整条指标),交回**整图的深拷贝**:别的节点、别的指标、图级扩展 + 字段和这条指标里没被换掉的键都在。map 里有卡上不存在的 id 时 MetricGone——首版不支持用字段操作新增指标。""" + wanted = {str(key): value for key, value in metrics.items()} + known = set(self.ids()) + for metric_id in wanted: + if metric_id not in known: + raise MetricGone(metric_id) + graph = copy.deepcopy(self._graph) + node = next(item for item in graph.get("nodes") or [] if str(item.get("id")) == self.card_id) + data = node.get("data") + if not isinstance(data, dict): + data = node["data"] = {} + config = data.get("config") + if not isinstance(config, dict): + config = data["config"] = {} + replaced: list[Any] = [] + for metric in self._metrics_of(node): + metric_id = str(metric.get("id") or "") if isinstance(metric, dict) else "" + replaced.append(copy.deepcopy(wanted[metric_id]) if metric_id in wanted else metric) + config["metrics"] = replaced + return graph + + def definition_hash(self) -> str: + """这张卡的指标定义指纹(data/caliber_identity:只取语义字段,空值不进哈希,指标按 id 排序)。""" + from app.data.caliber_identity import definition_hash + + card = self.card + return definition_hash(card.caliber, card.caliber_version, self._metrics()) + + def _metrics(self) -> list[Any]: + return self._metrics_of(self._node) + + @staticmethod + def _metrics_of(node: Mapping[str, Any]) -> list[Any]: + metrics = _config_of(node).get("metrics") + return metrics if isinstance(metrics, list) else [] + + +__all__ = ["CaliberCard", "CaliberGone", "GraphBackedCaliberRepository", "MetricGone"] diff --git a/backend/app/ledger/review.py b/backend/app/ledger/review.py new file mode 100644 index 00000000..35a4ec94 --- /dev/null +++ b/backend/app/ledger/review.py @@ -0,0 +1,148 @@ +"""最小审阅(K05):对一条验证记录的 confirmed / rejected 决定,**只追加**,绑定认证主体、确认范围和所审依据。 + +**为什么要有它。** 「样例对得上」和「这条口径可以正式用」是两件事:前者是机器/夹具能判的(validation 里的 matched), +后者要一个**认证主体**看着定义和依据说一句。没有这一层,自动匹配就成了变相的批准;有了它,界面上的「验证通过」才有 +明确的责任人。 + +**模型不能写审批人。** 这里没有从请求体或模型回复取 actor 的路径:主体一律来自服务端身份(app.api.deps.current_principal), +连「关登录时自报的署名」和「认证过的用户名」也分开记在一个 verified 标志里。决定的内容只有 confirmed / rejected +(不建多级审批,也不做「样例匹配自动变成 confirmed」)。 + +**审的是依据,不是这张卡现在的样子。** 每条决定都记下**所审记录**的定义指纹、绑定指纹、取数语义指纹和方法版本 +(basis)。定义或绑定改过之后,旧决定仍在(历史可追),但不算覆盖新版本(covers_current=False)——所以「删掉一段 +没验证过的业务描述」不会让旧的审阅自动升级成对新定义的批准(E15/R07)。三样指纹里**任一侧缺失**(旧行没有、 +算不出来)同样算不覆盖:缺证据不得升级。 + +**确认范围要说清。** metrics 不写 = 确认这份记录的全部指标;写一个子集 = 只确认那几条;写空列表直接拒 +(空范围不是「确认全部」,是「什么也没确认」)。只确认一部分时,草稿摘要不会给卡级 verified——它把还没确认的 +指标列在 `unconfirmed` 里(卡级通过要求确认范围盖住这份记录的全部指标)。 +""" +from __future__ import annotations + +import logging +from collections.abc import Mapping, Sequence +from typing import Any + +logger = logging.getLogger(__name__) + +CONFIRMED = "confirmed" +REJECTED = "rejected" +DECISIONS = (CONFIRMED, REJECTED) + + +class ReviewRefused(ValueError): + """这次审阅不合规(接口回 422):message 给人看,code 是机器码。""" + + def __init__(self, message: str, *, code: str = "review_invalid") -> None: + super().__init__(message) + self.message = message + self.code = code + + +def basis_of(record: Any) -> dict[str, Any]: + """所审记录的依据版本:审的是这一份依据,不是「这张卡现在长什么样」。""" + return {"version": int(getattr(record, "version", 0) or 0), + "definition_hash": str(getattr(record, "definition_hash", "") or ""), + "binding_fingerprints": dict(getattr(record, "binding_fingerprints", None) or {}), + "semantic_hash": str(getattr(record, "semantic_hash", "") or ""), + "method_version": int(getattr(record, "method_version", 0) or 0)} + + +def scope_of(record: Any, wanted: Sequence[str] | None = None) -> list[str]: + """确认范围:这份记录覆盖的指标;给了 wanted 就按那个子集,但**不能是空的、也不能超出这份记录**。 + + wanted 不给 = 确认这份记录覆盖的全部指标。写着一个空列表不算「确认全部」——那是「什么也没确认」, + 卡级通过要求确认范围盖住记录的全部指标,所以空范围在这里直接拒(要确认全部就别写这一项)。 + """ + covered = [str(mid) for mid in getattr(record, "metric_ids", None) or []] + if wanted is None: + return covered + asked = [str(mid) for mid in wanted] + if not asked: + raise ReviewRefused("确认范围不能是空的:要确认这份记录全部指标就别写 metrics 这一项;" + "只确认其中几条就写那几条", code="review_scope") + unknown = [mid for mid in asked if mid not in covered] + if unknown: + raise ReviewRefused(f"这份验证记录没有覆盖这些指标:{'、'.join(unknown)}", code="review_scope") + return list(dict.fromkeys(asked)) + + +def check(decision: Any) -> str: + """决定只有 confirmed / rejected;别的写法一律拒(不给「默认确认」这种方便)。""" + text = str(decision or "").strip() + if text not in DECISIONS: + raise ReviewRefused(f"审阅决定只能是 confirmed(确认)或 rejected(驳回),现在是「{text or '(空)'}」", + code="review_decision") + return text + + +async def decide(session: Any, *, draft_id: str, record: Any, decision: str, actor: str | None, + verified: bool = False, scope: Sequence[str] | None = None, note: str | None = None + ) -> Any: + """追加一条审阅决定,绑定认证主体、确认范围和所审记录的依据。不提交:和这次请求同一个事务。""" + from app.db.models import CaliberReviewDecision + + text = check(decision) + row = CaliberReviewDecision( + draft_id=draft_id, record_id=str(getattr(record, "id", "")), + workflow_id=str(getattr(record, "workflow_id", "") or "") or None, decision=text, actor=actor, + verified=bool(verified), scope=scope_of(record, scope), basis=basis_of(record), + note=(str(note).strip() or None) if note is not None else None) + session.add(row) + await session.flush() + return row + + +def covers_current(decision: Any, *, current: Mapping[str, Any] | None) -> bool: + """这条决定还算不算覆盖**当前**定义和绑定:按它记下的 basis 和当前依据比,**任一侧缺失都算不覆盖**。 + + 定义指纹、取数语义指纹少一个(旧行没有、算不出来)时一律 False:缺证据不得自动升级成「已确认当前版本」。 + """ + if not isinstance(current, Mapping): + return False + basis = getattr(decision, "basis", None) or {} + if not str(basis.get("definition_hash") or "") or not str(getattr(decision, "workflow_id", "") or ""): + return False + if str(getattr(decision, "workflow_id", "")) != str(current.get("workflow_id") or ""): + return False + if str(basis.get("definition_hash")) != str(current.get("definition_hash") or ""): + return False + if dict(basis.get("binding_fingerprints") or {}) != dict(current.get("binding_fingerprints") or {}): + return False + recorded, live = str(basis.get("semantic_hash") or ""), str(current.get("semantic_hash") or "") + if not recorded or not live or recorded != live: + return False + return True + + +def as_dict(row: Any, *, current: Mapping[str, Any] | None = None) -> dict[str, Any]: + """一条审阅决定的对外形状。covers_current 说明它还算不算覆盖当前定义/绑定。""" + return {"id": row.id, "draft_id": row.draft_id, "record_id": row.record_id, + "workflow_id": row.workflow_id, "decision": row.decision, "actor": row.actor, + "verified": bool(row.verified), "scope": [str(mid) for mid in row.scope or []], + "basis": dict(row.basis or {}), "note": row.note, + "created_at": row.created_at.isoformat() if getattr(row, "created_at", None) else None, + "covers_current": covers_current(row, current=current) if isinstance(current, Mapping) else None} + + +async def latest_by_record(session: Any, record_ids: Sequence[str], *, current: Mapping[str, Any] | None = None + ) -> dict[str, dict[str, Any]]: + """这些验证记录上最新的审阅决定:record_id → 决定(对外形状)。没有决定的记录不出现在结果里。""" + from sqlalchemy import select + + from app.db.models import CaliberReviewDecision + + wanted = [str(rid) for rid in record_ids if rid] + if not wanted: + return {} + rows = (await session.execute( + select(CaliberReviewDecision).where(CaliberReviewDecision.record_id.in_(wanted)) + .order_by(CaliberReviewDecision.created_at.asc(), CaliberReviewDecision.id.asc()))).scalars() + out: dict[str, dict[str, Any]] = {} + for row in rows: # 按时间升序扫,后写的覆盖先写的:显示用最新那一条(旧的一条都没删) + out[str(row.record_id)] = as_dict(row, current=current) + return out + + +__all__ = ["CONFIRMED", "DECISIONS", "REJECTED", "ReviewRefused", "as_dict", "basis_of", "check", + "covers_current", "decide", "latest_by_record", "scope_of"] diff --git a/backend/app/ledger/validation.py b/backend/app/ledger/validation.py new file mode 100644 index 00000000..2008e60b --- /dev/null +++ b/backend/app/ledger/validation.py @@ -0,0 +1,595 @@ +"""验证记录(K05):试跑完成时**追加**一条,说清这次在什么定义和绑定上、拿什么输入、和什么独立期望比、结果是什么。 + +**试跑成功、绑定对齐、业务确认、正式可用是四件不同的事。** 这张表(caliber_validation_records)只记前两件里能被 +证据支持的那部分: + +- 有独立期望(人工确认 / 固定 fixture / 独立计算)并且逐条对得上 → `matched`; +- 有期望但对不上 → `mismatched`; +- **没有期望 → `observed`**:跑了、取了数,但没有可比的标准答案,一个字也不能说「通过」;证据不足(遮罩、缺指标、 + 读不到查询快照)→ `unverified`;运行没成功 → `failed`。 +- 样例匹配**不等于**正式批准:`matched` 只是「这一次和这份期望对得上」。批准是 ReviewDecision(app/ledger/review.py), + 要认证主体显式做,见 summarize 的 verdict。 + +**覆盖是读的时候现算的。** 定义指纹、绑定指纹、取数语义指纹(semantic_hash,含 SQL 和数据源)三者任一变了,旧记录 +就**不再算覆盖当前版本**(covers_current=False)——不是把旧记录删掉或改写:历史照旧可追,只是不能拿它给新定义背书。 +删掉语义字段(没验证过的业务描述)会改定义指纹,因此旧记录立刻失去覆盖,不会「因为缺了这段描述就升级成通过」(E15/R07)。 +布局变更不改这些指纹,所以移动画布不会白白作废验证(4.1)。 + +**方法版本 1 的比较口径(写死在这里,随版本说清):** + +- **原值比较,不做隐式舍入**(R06):直接比取数得到的那个值,不四舍五入、不截位、不归一百分号。数字按数值相等 + (2 与 2.0 同),布尔和数字不混,字符串逐字比。 +- **全指标比较**:给了期望就要逐条给(卡片上的每条指标都得有),漏一条就报出来,不拿「只比了几条」当通过。 +- **全约定形状比较**(R04/R05):声明成标量的指标必须**恰好一行**。空结果(0 行)和多行都不是「取第一行就对」—— + 0 行没有值,多行是标量取数有歧义,两种情况都算形状不满足。形状读不到(没有查询快照、被截断)时不判对,记 unverified。 +- 运行期已判出来的约束问题(app/engine/metric_spec.contract_findings 的结论、no_data 等)一并记进这一行,不重复解释。 + +**追加与去重。** 一行 = 一次试跑的一次终态;同一 (草稿, trial_id, status) 只落一行(重复保存同一次终态不新增)。 +晚结束的旧试跑即使不能替换当前 trial 指针,也照旧追加自己这一行:新旧记录都留着,读的时候按各自的定义/绑定依据 +算覆盖。 +""" +from __future__ import annotations + +import logging +from collections.abc import Iterable, Mapping, Sequence +from typing import Any + +from sqlalchemy.exc import IntegrityError + +logger = logging.getLogger(__name__) + +#: 比较方法本身的版本。改了 compare 的语义(比较口径、形状规则)就 +1:记录里记着这一版,历史结果才知道是按哪一版判的。 +METHOD_VERSION = 1 +#: 这一版比较方法的一句话说明(接口原样交给界面和外部集成) +METHOD_NOTE = ("原值比较、不做隐式舍入;逐条比较卡上全部指标;声明成标量的指标必须恰好一行," + "空结果与多行都不算通过;形状判不了时记 unverified") + +#: 记录的状态。**没有 pass / verified 这种状态**:验证通过与否是 summarize 按「覆盖 + 期望 + 审阅」现算的结论。 +MATCHED = "matched" # 有独立期望,逐条对得上,形状也满足 +MISMATCHED = "mismatched" # 有独立期望,至少一条对不上(含期望没覆盖全部指标、形状不满足) +OBSERVED = "observed" # 跑了、取了数,但没有独立期望:不能算验证通过 +UNVERIFIED = "unverified" # 证据不足:遮罩、缺指标、形状判不了,或这次试跑没对着当前定义 +FAILED = "failed" # 运行没成功 +STATUSES = (MATCHED, MISMATCHED, OBSERVED, UNVERIFIED, FAILED) + +#: 期望来自哪里。**不能把当前 SQL 的结果抄一份当标准答案**:来源必须是独立于这次执行的一方。 +EXPECTATION_SOURCES = ("human_confirmed", "fixture", "independent_computation") +DEFAULT_EXPECTATION_SOURCE = "human_confirmed" +#: 一次运行里已经被判出来的形状/取值问题(engine 的质量检查码):一并记进记录,不另解释一遍 +FINDING_CODES = ("metric_contract", "no_data", "value", "incomplete", "recompute") + + +# ========================================================================== +# 依据:这次验证绑的是哪一份定义和绑定 +# ========================================================================== + + +def _card_config(graph: Any, card_id: Any) -> dict[str, Any]: + for node in (graph or {}).get("nodes") or []: + if isinstance(node, Mapping) and str(node.get("id")) == str(card_id): + config = (node.get("data") or {}).get("config") if isinstance(node.get("data"), Mapping) else None + return dict(config) if isinstance(config, Mapping) else {} + return {} + + +def card_metrics(graph: Any, card_id: Any) -> list[dict[str, Any]]: + """这张源头口径卡上的指标(有 id 的那些),顺序照图里。""" + metrics = _card_config(graph, card_id).get("metrics") + return [dict(m) for m in metrics if isinstance(m, Mapping) and m.get("id")] if isinstance(metrics, list) else [] + + +def definition_hash(graph: Any, card_id: Any) -> str: + """这张卡的定义指纹(data/caliber_identity:只按语义字段算)。和仓储、变更服务用的是同一份。""" + from app.data.caliber_identity import definition_hash as hash_of + + config = _card_config(graph, card_id) + return hash_of(str(config.get("caliber") or ""), str(config.get("caliber_version") or ""), + card_metrics(graph, card_id)) + + +def semantic_fingerprint(graph: Any, card_id: Any) -> str: + """这张卡及其上游执行依赖的指纹(含取数 SQL、数据源、入口绑定;不含布局)。读不出来时给空串,照实说不判。""" + from app.data.caliber_identity import semantic_hash + + try: + return semantic_hash(dict(graph or {}), str(card_id)) + except Exception: # noqa: BLE001 - 指纹算不出来不该让一次试跑没了记录,照实留空 + logger.warning("口径「%s」的取数语义指纹算不出来", card_id, exc_info=True) + return "" + + +def binding_fingerprints(graph: Any, card_id: Any) -> dict[str, str]: + """这张卡的取数节点绑定指纹(K04:node_id → 绑定指纹)。没声明绑定、认不出的节点不进这里。""" + from app.ledger import bindings + + try: + return {str(node): str(value) for node, value in bindings.analyze(graph or {}, str(card_id)).fingerprints.items()} + except Exception: # noqa: BLE001 - 绑定判定出错时留空,不让它把记录弄没 + logger.warning("口径「%s」的绑定指纹算不出来", card_id, exc_info=True) + return {} + + +def materials(graph: Any, card_id: Any, *, workflow_id: str = "") -> dict[str, Any]: + """一次验证要绑定的全部依据:卡、定义指纹、绑定指纹、取数语义指纹(另带这份资产的工作流 id)。""" + return {"workflow_id": str(workflow_id or ""), "card_id": str(card_id or ""), + "definition_hash": definition_hash(graph, card_id), + "binding_fingerprints": binding_fingerprints(graph, card_id), + "semantic_hash": semantic_fingerprint(graph, card_id)} + + +def covers_current(row: Any, *, current: Mapping[str, Any]) -> bool: + """这条记录还算不算覆盖**当前**定义和绑定:三样指纹都要对得上,而且三样都得有值(定义、绑定、取数语义)。 + + 布局变更不在这些指纹里,所以移动画布不作废验证;改了定义、改了 SQL、改了数据源或绑定就对不上了。 + **任一侧缺失都算不覆盖**:定义指纹、取数语义指纹少一个(算不出来、旧行没有、工件对不上)时一律 False—— + 「缺证据」不得自动升级成覆盖。 + """ + if not isinstance(current, Mapping): + return False + recorded_definition = str(getattr(row, "definition_hash", "") or "") + live_definition = str(current.get("definition_hash") or "") + if not recorded_definition or not live_definition or recorded_definition != live_definition: + return False + if str(getattr(row, "workflow_id", "") or "") != str(current.get("workflow_id") or ""): + return False + if str(getattr(row, "card_id", "") or "") != str(current.get("card_id") or ""): + return False + if dict(getattr(row, "binding_fingerprints", None) or {}) != dict(current.get("binding_fingerprints") or {}): + return False + recorded_semantics = str(getattr(row, "semantic_hash", "") or "") + live_semantics = str(current.get("semantic_hash") or "") + if not recorded_semantics or not live_semantics or recorded_semantics != live_semantics: + return False + return True + + +# ========================================================================== +# 实际值:这次跑出来的每个指标的值和形状 +# ========================================================================== + + +def declared_shapes(metrics: Iterable[Mapping[str, Any]]) -> dict[str, str | None]: + """卡片上每条指标声明了什么结果形状(contract.shape);没声明的是 None(不替它判)。""" + out: dict[str, str | None] = {} + for metric in metrics: + if not isinstance(metric, Mapping) or not metric.get("id"): + continue + contract = metric.get("contract") if isinstance(metric.get("contract"), Mapping) else {} + shape = contract.get("shape") + out[str(metric["id"])] = shape if isinstance(shape, str) and shape.strip() else None + return out + + +def _shape_of(*, shape: str | None, rows: int | None, truncated: bool) -> tuple[bool | None, list[str]]: + """形状判不判得过:返回 (ok, 说明)。ok 是 None 表示判不了(没有查询快照)。""" + if rows is None: + return None, ["这次运行没有可核对的查询快照:形状判不了(不算通过)"] + if rows == 0: + return False, ["取数结果 0 行(空结果):标量没有可取的数,不能当作取到了值"] + if shape == "scalar": + if truncated: + return False, ["查询被截断,标量要求恰好一行这一条没法核对"] + if rows != 1: + return False, [f"标量指标要求取数结果恰好一行,实际为 {rows} 行:不拿第一行当结果"] + return True, [] + + +def actual_of(*, metrics: Sequence[Mapping[str, Any]], queries: Sequence[Mapping[str, Any]], + card_metrics_: Sequence[Mapping[str, Any]], metric_ids: Sequence[str], + links: Mapping[str, str] | None = None) -> dict[str, dict[str, Any]]: + """这次运行交回的实际值:metric_id → {value, status, rows, masked, shape, shape_ok, findings}。 + + metrics 是接口层读运行证据得到的那一份(app/api/ledger.py 的 _trial_metrics)。**指标记录本身不带取数节点**: + 真实运行的关联由调用方从封存的口径卡里认出来,通过 links(metric_id → 查询快照的键:工件 id 或取数节点 id)传进来; + 没有 links 时退回指标自带的 node_id(桩和测试用)。queries 每项要有 key(或 node_id)+ total_rows + truncated。 + + 按**行数、截断和引擎已判出来的约束结论**判形状——**不看第一行**。对不上任何快照的指标记 rows=None(形状判不了), + 照实记 unverified,不猜。 + """ + shape_of_metric = declared_shapes(card_metrics_) + by_key: dict[str, Mapping[str, Any]] = {} + for query in queries if isinstance(queries, Sequence) else []: + if not isinstance(query, Mapping): + continue + for key in (query.get("key"), query.get("node_id")): + # 一个节点跑过多次时后来的那份快照算数(指标取的是它最后一次交回的结果) + if isinstance(key, str) and key: + by_key[key] = query + known = {str(m.get("id")): m for m in metrics if isinstance(m, Mapping) and m.get("id")} + wanted_by_metric = dict(links or {}) + out: dict[str, dict[str, Any]] = {} + for metric_id in metric_ids: + item = known.get(str(metric_id)) + shape = shape_of_metric.get(str(metric_id)) + if item is None: + out[str(metric_id)] = {"value": None, "status": "missing", "rendered": "", "rows": None, + "masked": False, "truncated": False, "shape": shape, "shape_ok": None, + "findings": ["这次运行没有交回这条指标的结果"]} + continue + key = wanted_by_metric.get(str(metric_id)) or item.get("node_id") + query = by_key.get(str(key)) if isinstance(key, str) and key else None + rows = query.get("total_rows") if isinstance(query, Mapping) else None + rows = int(rows) if isinstance(rows, int) and not isinstance(rows, bool) else None + truncated = bool(query.get("truncated")) if isinstance(query, Mapping) else False + ok, shape_notes = _shape_of(shape=shape, rows=rows, truncated=truncated) + findings = [str(check.get("detail")) for check in ((item.get("quality") or {}).get("checks") or []) + if isinstance(check, Mapping) and check.get("code") in FINDING_CODES and check.get("detail")] + # 引擎判过「业务描述和取数条件的关系还没被证明」(semantic_unverified)时照实记下来:它是**待人工确认**的 + # 缺口,不是这次比较的结论——所以不并进 problems(那会把 matched 降成 unverified),但也不能被藏起来。 + semantic = any(isinstance(check, Mapping) and check.get("code") == "semantic_definition" + for check in ((item.get("quality") or {}).get("checks") or [])) + out[str(metric_id)] = {"value": item.get("value"), "status": str(item.get("status") or ""), + "rendered": item.get("rendered"), "rows": rows, "masked": bool(item.get("masked")), + "truncated": truncated, "shape": shape, "shape_ok": ok, + "semantic_unverified": semantic, + "findings": list(dict.fromkeys([*shape_notes, *findings]))} + return out + + +# ========================================================================== +# 比较:期望 vs 实际 +# ========================================================================== + + +def same_value(expected: Any, actual: Any) -> bool: + """原值比较,不做隐式舍入(R06):数字按数值相等(2 与 2.0 同),布尔与数字不混,其余按规范化 JSON 逐字比。""" + from app.core.artifact_store import canonical_json + + if isinstance(expected, bool) != isinstance(actual, bool): + return False + if isinstance(expected, (int, float)) and isinstance(actual, (int, float)): + return bool(expected == actual) + return canonical_json(expected) == canonical_json(actual) + + +def _label(metric_id: str, card_metrics_: Sequence[Mapping[str, Any]]) -> str: + for metric in card_metrics_: + if isinstance(metric, Mapping) and str(metric.get("id")) == str(metric_id): + name = metric.get("name") + return str(name) if name else str(metric_id) + return str(metric_id) + + +def compare(*, expected: Mapping[str, Any] | None, actual: Mapping[str, Mapping[str, Any]], + metric_ids: Sequence[str], card_metrics_: Sequence[Mapping[str, Any]], + run_status: str = "succeeded", problems: Iterable[str] = ()) -> dict[str, Any]: + """把独立期望和这次的实际值比一遍,返回 {status, problems, actual}。 + + - 没有期望:只记 observed(有形状/取值问题也照实写进 problems),**不能**是 matched; + - 有期望:逐条对,缺一条期望算 mismatched(全指标比较);形状判不了算 unverified;对不上算 mismatched。 + """ + listed = list(dict.fromkeys(str(p) for p in problems)) + detail: dict[str, dict[str, Any]] = {str(mid): dict(actual.get(str(mid)) or {}) for mid in metric_ids} + if run_status != "succeeded": + status = FAILED if run_status == "failed" else UNVERIFIED + return {"status": status, "problems": [*listed, "这次试运行没有成功,没有可比较的实际结果"], + "actual": detail} + if not metric_ids: + # 一条可比对的指标都没有(找不到定义依据,或卡上本来就没有指标):缺证据不得升级成通过 + return {"status": UNVERIFIED, + "problems": list(dict.fromkeys([*listed, "这次没有可比对的指标:找不到这次试运行的定义依据," + "不能算验证通过"])), + "actual": detail} + shape_bad = False + unknown = False + for metric_id in metric_ids: + entry = detail[str(metric_id)] + name = _label(str(metric_id), card_metrics_) + for finding in entry.get("findings") or []: + listed.append(f"指标「{name}」:{finding}") + if entry.get("shape_ok") is False: + shape_bad = True + elif entry.get("shape_ok") is None: + unknown = True + if expected is None: + return {"status": OBSERVED, + "problems": list(dict.fromkeys([*listed, "这次试运行没有独立期望:只记 observed,不能算验证通过"])), + "actual": detail} + mismatched = False + for metric_id in metric_ids: + entry = detail[str(metric_id)] + name = _label(str(metric_id), card_metrics_) + if str(metric_id) not in expected: + mismatched = True + entry["expected"], entry["ok"] = None, False + listed.append(f"期望没有覆盖指标「{name}」:希望逐条给全卡指标,不能只比其中几条") + continue + want = expected[str(metric_id)] + entry["expected"] = want + if entry.get("masked"): + unknown = True + entry["ok"] = None + listed.append(f"指标「{name}」的值已遮罩:不能在这里判对得上") + continue + if entry.get("status") == "missing": + unknown = True + entry["ok"] = None + listed.append(f"指标「{name}」这次没有结果:判不了") + continue + got = entry.get("value") + if got is None and want is not None: + mismatched = True + entry["ok"] = False + listed.append(f"指标「{name}」期望 {want!r},实际没有取到值") + continue + ok = same_value(want, got) + entry["ok"] = ok + if not ok: + mismatched = True + listed.append(f"指标「{name}」对不上:期望 {want!r},实际 {got!r}") + if mismatched or shape_bad: + return {"status": MISMATCHED, "problems": list(dict.fromkeys(listed)), "actual": detail} + if unknown or listed: + return {"status": UNVERIFIED, "problems": list(dict.fromkeys(listed)), "actual": detail} + return {"status": MATCHED, "problems": [], "actual": detail} + + +# ========================================================================== +# 追加一行 +# ========================================================================== + + +def expectation_of(expect: Any, *, card_metrics_: Sequence[Mapping[str, Any]]) -> dict[str, Any] | None: + """把接口交来的期望规范成要落库的那一份;给不出可用期望时返回 None。 + + 形状是 {"source": …, "metrics": {metric_id: 值}, "note": …, "sample_id": …, "sample_version": …}:值原样留着 + (比较按原值),来源记下来供人判断「这份期望是谁给的、凭什么」。 + """ + if not isinstance(expect, Mapping): + return None + metrics = expect.get("metrics") + if not isinstance(metrics, Mapping) or not metrics: + return None + known = {str(m.get("id")) for m in card_metrics_ if isinstance(m, Mapping) and m.get("id")} + kept = {str(mid): value for mid, value in metrics.items() if str(mid) in known} + if not kept: + return None + source = expect.get("source") + source = str(source) if isinstance(source, str) and source in EXPECTATION_SOURCES else DEFAULT_EXPECTATION_SOURCE + out: dict[str, Any] = {"source": source, "metrics": kept} + for key in ("note", "sample_id", "sample_version"): + value = expect.get(key) + if isinstance(value, str) and value.strip(): + out[key] = value.strip() + return out + + +def expectation_hash(expectation: Mapping[str, Any] | None) -> str: + """期望的内容指纹:这一行到底对的哪一份期望(改了期望再来一次,指纹不同,两条记录看得出来不是一回事)。""" + from app.core.artifact_store import canonical_json, content_hash + + return content_hash(canonical_json(expectation)) if expectation else "" + + +async def append(*, draft_id: str, workflow_id: str | None, version: int, card_id: str, metric_ids: Sequence[str], + basis: Mapping[str, Any], inputs: Mapping[str, Any], inputs_hash: str, trial_id: str, run_id: str, + actor: str | None, status: str, problems: Sequence[str], expectation: Mapping[str, Any] | None, + actual: Mapping[str, Any], execution_hash: str = "", sample: Mapping[str, Any] | None = None, + origin: str = "trial") -> str | None: + """追加一条验证记录;同一 (草稿, trial_id, status) 已经有一条时不再新增。 + + 新会话、独立事务:草稿 payload 的写入可能因为并发被拒,但**记录照旧要落**——晚结束的旧试跑也能被追踪。 + 任何落库错误都只记警告:记录写不下不该让试跑本身失败。 + """ + from app.db.base import SessionLocal + from app.db.models import CaliberValidationRecord + + if status not in STATUSES: + status = UNVERIFIED + sample = sample if isinstance(sample, Mapping) else {} + try: + async with SessionLocal() as session: + existing = (await session.execute( + select_record(draft_id, trial_id, status))).scalar_one_or_none() + if existing is not None: + return existing.id + row = CaliberValidationRecord( + draft_id=draft_id, workflow_id=workflow_id or None, version=int(version or 1), + card_id=str(card_id or ""), metric_ids=[str(mid) for mid in metric_ids], + definition_hash=str(basis.get("definition_hash") or ""), + binding_fingerprints={str(k): str(v) for k, v in (basis.get("binding_fingerprints") or {}).items()}, + semantic_hash=str(basis.get("semantic_hash") or ""), execution_hash=str(execution_hash or ""), + expectation=dict(expectation) if expectation else None, expectation_hash=expectation_hash(expectation), + expectation_source=str((expectation or {}).get("source") or ""), + sample_id=str(sample.get("id") or (expectation or {}).get("sample_id") or ""), + sample_version=str(sample.get("version") or (expectation or {}).get("sample_version") or ""), + inputs=dict(inputs or {}), inputs_hash=str(inputs_hash or ""), method_version=METHOD_VERSION, + actual={str(mid): dict(entry) for mid, entry in (actual or {}).items()}, + status=status, problems=[str(p) for p in problems], trial_id=str(trial_id or ""), + run_id=str(run_id or ""), actor=actor, origin=origin) + session.add(row) + try: + await session.commit() + except IntegrityError: # noqa: F821 - 并发下同一 (草稿, trial_id, status) 先被别人写进去了 + await session.rollback() + existing = (await session.execute( + select_record(draft_id, trial_id, status))).scalar_one_or_none() + return existing.id if existing is not None else None + return row.id + except Exception: # noqa: BLE001 - 记录写不下不该让试跑本身失败 + logger.exception("验证记录写不下(草稿 %s,试跑 %s)", draft_id, trial_id) + return None + + +def select_record(draft_id: str, trial_id: str, status: str) -> Any: + """同一 (草稿, trial_id, status) 的那一行(唯一键的认法,和表上的约束一致)。""" + from sqlalchemy import select + + from app.db.models import CaliberValidationRecord + + return select(CaliberValidationRecord).where( + CaliberValidationRecord.draft_id == draft_id, + CaliberValidationRecord.trial_id == str(trial_id or ""), + CaliberValidationRecord.status == status) + + +async def list_for_draft(session: Any, draft_id: str) -> list[Any]: + """一份草稿的验证记录,新的在前。""" + from sqlalchemy import select + + from app.db.models import CaliberValidationRecord + + return list((await session.execute( + select(CaliberValidationRecord).where(CaliberValidationRecord.draft_id == draft_id) + .order_by(CaliberValidationRecord.created_at.desc(), CaliberValidationRecord.id.desc()))).scalars()) + + +async def get_record(session: Any, draft_id: str, record_id: str) -> Any: + """这份草稿上的某一条记录;不是它的一律当不存在(不跨草稿读)。""" + from sqlalchemy import select + + from app.db.models import CaliberValidationRecord + + return (await session.execute(select(CaliberValidationRecord).where( + CaliberValidationRecord.id == record_id, + CaliberValidationRecord.draft_id == draft_id))).scalar_one_or_none() + + +async def find_record(session: Any, draft_id: str, trial_id: str) -> Any: + """这次试运行留下的那条记录;没有就是 None。 + + 同一个身份(trial_id / run_id)可能有多条行(同一次试运行在不同状态下各落一行,比如先 observed、后有期望 + 再跑成 matched):给**最新的一条**。**不给别的试运行的记录**,也不在找不到时退回「整份草稿最新的一条」。 + """ + from sqlalchemy import select + + from app.db.models import CaliberValidationRecord + + if not trial_id: + return None + rows = (await session.execute( + select(CaliberValidationRecord).where( + CaliberValidationRecord.draft_id == draft_id, + CaliberValidationRecord.trial_id == str(trial_id)) + .order_by(CaliberValidationRecord.created_at.desc(), CaliberValidationRecord.id.desc()) + .limit(1))).scalars() + return rows.first() + + +# ========================================================================== +# 读:K06 要的那份契约 +# ========================================================================== + + +def as_dict(row: Any, *, current: Mapping[str, Any] | None = None, review: Mapping[str, Any] | None = None + ) -> dict[str, Any]: + """一条记录的对外形状:期望、实际、状态、覆盖判断、审阅,一次给全。 + + `covers_current` 是拿记录里的依据和**当前**定义/绑定比出来的(current 不给时是 None:调用方没有当前依据, + 不替它猜)。`review` 是这条记录上最新的一次审阅决定(没有就是 None),**样例匹配不会自动变成审阅通过**。 + """ + covered = covers_current(row, current=current) if isinstance(current, Mapping) else None + return { + "id": row.id, "draft_id": row.draft_id, "workflow_id": row.workflow_id, "version": row.version, + "card_id": row.card_id, "metric_ids": [str(mid) for mid in row.metric_ids or []], + "definition_hash": row.definition_hash, "binding_fingerprints": dict(row.binding_fingerprints or {}), + "semantic_hash": row.semantic_hash, "execution_hash": row.execution_hash, + "method": {"version": row.method_version, "note": METHOD_NOTE}, + "sample": {"id": row.sample_id, "version": row.sample_version}, + "inputs": dict(row.inputs or {}), "inputs_hash": row.inputs_hash, + "expected": ({"source": row.expectation_source or DEFAULT_EXPECTATION_SOURCE, + "metrics": dict((row.expectation or {}).get("metrics") or {}), + "note": (row.expectation or {}).get("note"), + "hash": row.expectation_hash} + if row.expectation else None), + "actual": {str(mid): dict(entry) for mid, entry in (row.actual or {}).items()}, + "status": row.status, "problems": [str(p) for p in row.problems or []], + "run_id": row.run_id, "trial_id": row.trial_id, "actor": row.actor, "origin": row.origin, + "created_at": row.created_at.isoformat() if getattr(row, "created_at", None) else None, + "covers_current": covered, "review": dict(review) if isinstance(review, Mapping) else None, + } + + +def summarize(rows: Sequence[Any], *, current: Mapping[str, Any] | None = None, + reviews: Mapping[str, Mapping[str, Any]] | None = None) -> dict[str, Any]: + """一份草稿的验证总情况(草稿详情和验证列表共用这一份)。 + + 结论(verdict)只在「有覆盖当前定义/绑定的记录」的基础上说: + + | 情况 | verdict | + | --- | --- | + | 没有记录 | none | + | 有记录但没有一条覆盖当前定义/绑定 | stale | + | 覆盖的那条最新的状态是 mismatched / failed | mismatched / failed | + | 覆盖的那条没有独立期望 | observed(执行了,没标准答案) | + | 覆盖的那条是 unverified 或 matched 但**没有认证审阅** | unverified(样例匹配不是批准) | + | 覆盖的那条 matched 且有覆盖它、**且范围盖住全部指标**的 confirmed 审阅 | verified | + | 覆盖的那条被驳回,或只确认了其中一部分 | rejected / unverified(`unconfirmed` 列出还没确认的指标) | + + 另外两段:`confirmed` 是这次被确认到的指标(确认范围),`unconfirmed` 是这条记录覆盖但还没被确认的指标—— + **空范围或部分范围都不算整张卡通过**(卡级 verified 要求确认范围覆盖记录的全部指标)。 + """ + reviews = reviews or {} + counts = {status: 0 for status in STATUSES} + covering: list[Any] = [] + for row in rows: + counts[row.status] = counts.get(row.status, 0) + 1 + if isinstance(current, Mapping) and covers_current(row, current=current): + covering.append(row) + latest = (covering or list(rows))[0] if (covering or rows) else None + gaps = _semantic_gaps(latest) + note = (f";其中 {len(gaps)} 条指标的语义说明仍待人工确认(受控绑定对齐不等于业务描述已被证明)" + if gaps else "") + review = reviews.get(latest.id) if latest is not None else None + decision = str((review or {}).get("decision") or "") if isinstance(review, Mapping) else "" + review_covers = bool((review or {}).get("covers_current")) if isinstance(review, Mapping) else False + # 「确认了哪几条」:审阅的范围要和这份记录覆盖的指标对上;空范围或只确认了一部分,都不算整张卡被确认 + covered_ids = [str(mid) for mid in getattr(latest, "metric_ids", None) or []] if latest is not None else [] + confirmed_scope = [str(mid) for mid in (review or {}).get("scope") or []] \ + if isinstance(review, Mapping) and decision == "confirmed" and review_covers else [] + unconfirmed = [mid for mid in covered_ids if mid not in confirmed_scope] + fully_confirmed = bool(covered_ids) and not unconfirmed + if latest is None: + verdict, reason = "none", "这份草稿还没有试运行留下的验证记录" + elif not covering: + verdict = "stale" + reason = ("现有的验证记录都不是对着当前定义和绑定做出来的(定义、取数或绑定改过,或者现在读不到这份取数图):" + "旧记录留着可追,但不能算覆盖这一版,请重新试运行") + elif review_covers and decision == "rejected": + verdict, reason = "rejected", "有覆盖当前版本的记录,但它被审阅驳回了" + elif review_covers and decision == "confirmed": + if latest.status != MATCHED: + verdict = "unverified" + reason = f"审阅确认的是「{latest.status}」状态下的这一次:没有一条 matched 的记录覆盖当前版本" + elif not fully_confirmed: + verdict = "unverified" + reason = (f"审阅只确认了 {len(confirmed_scope)} 条,还有 {len(unconfirmed)} 条没被确认" + "(确认范围要覆盖这份记录的全部指标才算整张卡通过)") + else: + verdict, reason = "verified", "有独立期望的记录覆盖当前版本,并且有认证主体确认过全部指标" + note + elif latest.status == MATCHED: + verdict = "unverified" + reason = "有独立期望且对得上,但还没有认证审阅:样例匹配不等于正式批准" + elif latest.status == MISMATCHED: + verdict, reason = "mismatched", "有独立期望,但这一次没对上" + elif latest.status == FAILED: + verdict, reason = "failed", "这一次试运行没有成功" + elif latest.status == OBSERVED: + verdict, reason = "observed", "这次试运行执行了、也取到了数,但没有独立期望:不能算验证通过" + else: + verdict, reason = "unverified", "证据不足(遮罩、缺指标或形状判不了):不能算验证通过" + return {"verdict": verdict, "status": latest.status if latest is not None else "none", + "covers_current": bool(covering), "record_id": latest.id if latest is not None else None, + "review": dict(review) if isinstance(review, Mapping) else None, + "confirmed": confirmed_scope, "unconfirmed": unconfirmed, + "counts": {"total": len(rows), "covering": len(covering), **counts}, + "reason": reason, "semantic_gaps": gaps, + "method": {"version": METHOD_VERSION, "note": METHOD_NOTE}} + + +def _semantic_gaps(latest: Any) -> list[str]: + """这次(覆盖当前版本的那条)记录里,哪些指标的语义说明仍待人工确认(R07:受控绑定对齐不等于业务描述被证明)。 + + 它们不改变这一次的比较结论(该记 matched 还是 matched),但要能被人看见——「已确认」也不等于「这段描述被证明」。""" + if latest is None: + return [] + actual = getattr(latest, "actual", None) + return sorted(str(mid) for mid, entry in (actual or {}).items() + if isinstance(entry, Mapping) and entry.get("semantic_unverified")) + + +__all__ = ["DEFAULT_EXPECTATION_SOURCE", "EXPECTATION_SOURCES", "FAILED", "FINDING_CODES", "MATCHED", + "METHOD_NOTE", "METHOD_VERSION", "MISMATCHED", "OBSERVED", "STATUSES", "UNVERIFIED", "actual_of", + "append", "as_dict", "binding_fingerprints", "card_metrics", "compare", "covers_current", + "declared_shapes", "definition_hash", "expectation_hash", "expectation_of", "get_record", + "list_for_draft", "materials", "same_value", "semantic_fingerprint", "summarize"] diff --git a/backend/app/ledger/view.py b/backend/app/ledger/view.py index 2c72c336..8aec1ce6 100644 --- a/backend/app/ledger/view.py +++ b/backend/app/ledger/view.py @@ -28,6 +28,15 @@ from app.ledger import store #: state:matched 比对过;pending 已排队按需比对;ineligible 这次运行不比对(reason 写为什么);unreadable 比对记录读不出 STATES = ("matched", "pending", "ineligible", "unreadable") +#: 普通使用者看的口径账本里**不出去**的键(递归过一遍整份视图):口径的内部身份。人读的那一套——口径名(caliber、 +#: workflow_name)、级别叫法、指标与标签、每条查询的结果与证据关系、动作的说法、出具/对账的运行——都原样留着,只是认不出 +#: 「是哪一份工作流的哪一版」。builder 及以上拿到的是原件(run_view 只在普通使用者这一档过一遍)。 +USER_HIDDEN_KEYS = ("workflow_id", "workflow_version", "version", "graph_hash", "manifest", "manifest_hash", + "publication", "closure_hash", "selection_hash", "execution_hash", "identity") +#: 只在**口径标签/相关口径**那几处去掉的键:口径卡的节点 id(「是这张卡的哪个节点」是内部的事)。查询本身的 node_id +#: 是这次运行图上的节点,证据关系靠它,留着。 +USER_HIDDEN_LABEL_KEYS = ("node_id",) + #: 成功结束、还没封存的运行,结束后这么多秒内答 pending(runner 落库之后马上封存,正常是几秒)。过了还没封存的是封存出了错、 #: 或者是封存之前的老数据:再答 pending,页面就一直转圈、等满两分钟(store/ledger.ts 的等待上限)再取还是 pending——照实说没封存 SEAL_GRACE_S = 120 @@ -126,15 +135,104 @@ def _just_finished(finished_at: datetime | None) -> bool: return (datetime.now(timezone.utc) - at).total_seconds() <= SEAL_GRACE_S +def _scrub(value: Any) -> Any: + """递归过一遍:内部身份的键去掉(别的键、值、结构一个不动)。""" + if isinstance(value, dict): + return {k: _scrub(v) for k, v in value.items() if k not in USER_HIDDEN_KEYS} + if isinstance(value, list): + return [_scrub(v) for v in value] + return value + + +def _without(item: Any, keys: tuple[str, ...]) -> Any: + return {k: v for k, v in item.items() if k not in keys} if isinstance(item, dict) else item + + +def _name_in_place(item: dict[str, Any]) -> None: + """就地:口径那一栏的 `caliber` 是**内部键**(`工作流 id@版本`,ledger/labels.caliber_key),换成**人读的名字**。 + + 名字取不到(工作流删了)时去掉这一栏——宁可少一栏,也不把 id 交出去。别的一切原样。""" + key = item.get("caliber") + if isinstance(key, str) and "@" in key: + name = item.get("workflow_name") + if name: + item["caliber"] = str(name) + else: + item.pop("caliber", None) + + +def _named(item: Any) -> Any: + if not isinstance(item, dict): + return item + out = dict(item) + _name_in_place(out) + return out + + +def _action_view(item: Any) -> Any: + """一项动作:能不能做、为什么、级别叫法与身份都按同一套投影;**只有确实给这个人做的那一项**留着口径身份。 + + 出具与对账这两下都要带着 `workflow_id` + `version` 去发请求(`POST /api/ledger/answers/{run_id}/issue|reconcile`), + 而这两项只有在这个人**确实有权**(`available`:应用授权、比对等价、绑定没被遮)时才会给出来——服务端在收到请求时还会 + 再核一遍。被拒的那些项只是说明,不是操作凭据,身份不带出去(不然就成了拿别人的口径 id 探路)。""" + if not isinstance(item, dict): + return item + out = _named(_scrub(item)) + if item.get("available"): + for key in ("workflow_id", "version"): + if key in item: + out[key] = item[key] + return out + + +def label_user_view(label: dict[str, Any]) -> dict[str, Any]: + """一个标签交给普通使用者的那一份:口径身份不出去(卡节点 id、工作流 id、版本、哈希),指标与结论一个字不动。 + + 账本视图、证据片段的「口径」一步、报告导出读的是同一份标签(ledger/labels.view_label),三处按同一条规则投影。""" + out = _named(_scrub(label)) + out.pop("node_id", None) + out["related"] = [_named(_without(item, USER_HIDDEN_LABEL_KEYS)) for item in out.get("related") or []] + return out + + +def caliber_user_view(view: dict[str, Any]) -> dict[str, Any]: + """普通使用者看的口径账本(`/api/runs/{id}/ledger`):口径身份不出去,人读的部分一个字不动。 + + 去掉的:工作流 id / 版本号 / 清单引用 / 各种哈希(递归地)、口径标签里的卡节点 id、口径那一栏里的内部键(换成名字); + 只有「确实给这个人做」的动作(能出具、能对账)另带它要用的那两个身份。留着的:口径名(caliber、workflow_name)、 + 级别叫法、指标与标签、每条查询的结果、候选与证据关系、动作的说法(能不能出具、为什么)、出具与对账的运行和结论—— + 界面按这些画,一样不缺。builder 及以上不看这一份(run_view 里按 restricted() 分)。""" + out = _scrub(view) + out["calibers"] = [_named(c) for c in out.get("calibers") or []] + out["whole"] = _named(_without(out.get("whole"), USER_HIDDEN_LABEL_KEYS)) + out["actions"] = [_action_view(action) for action in view.get("actions") or []] + for query in out.get("queries") or []: + if not isinstance(query, dict): + continue + query["candidates"] = [_named(_without(c, USER_HIDDEN_LABEL_KEYS)) for c in query.get("candidates") or []] + for cell in (query.get("cells") or {}).values(): + if isinstance(cell, dict): + cell["candidates"] = [_named(_without(c, USER_HIDDEN_LABEL_KEYS)) + for c in cell.get("candidates") or []] + for report in (out.get("reports") or {}).values(): + if not isinstance(report, dict): + continue + report["labels"] = {sid: label_user_view(label) for sid, label in (report.get("labels") or {}).items() + if isinstance(label, dict)} + return out + + async def run_view(run_id: str) -> dict[str, Any]: """GET /api/runs/{run_id}/ledger 的答复:标签、整题判断、每条查询的比对、能做的动作。没比对过、能比的运行这时排上按需比对 (trigger=on_demand),答复 state=pending;不比的照实说为什么。""" from app.api.coded import CodedHTTPException + from app.api.deps import restricted from app.api.evidence import RUN_NOT_FOUND, _sealed from app.api.deps import current_principal from app.ledger.recall import answer_marks + ordinary = restricted() async with SessionLocal() as session: run = await session.get(Run, run_id) if run is None: @@ -176,7 +274,9 @@ async def run_view(run_id: str) -> dict[str, Any]: # 对账结果上的「说明有用 / 看不懂」(ledger/feedback):看的这个人给过哪一个、各几个 votes = await ledger_feedback.feedback_of(session, [r["run_id"] for r in reconciled], principal) reconciled = [{**r, "feedback": votes[r["run_id"]]} for r in reconciled] - return { + # 对账这一项能不能做:同一份资产授权判定(reconcile.actions_of 里按这个身份给 available;无权的那些不带身份) + reconcile_actions = await ledger_reconcile.actions_of(session, content, names, hider.hide, actor=principal) + view = { **base, "state": "matched", **_stamp(recorded), "calibers": [{**{k: c.get(k) for k in ("caliber", "workflow_id", "version", "level", "graph_hash")}, "workflow_name": names.get(str(c.get("workflow_id") or "")), @@ -186,15 +286,21 @@ async def run_view(run_id: str) -> dict[str, Any]: "reports": _labels_view(content, hider, names), "primary": content.get("primary"), "whole": _whole_view(content.get("whole") or {}, hider, names), - "actions": [*(p.action() for p in plans), *ledger_reconcile.actions_of(content, names, hider.hide)], + "actions": [*(p.action() for p in plans), *reconcile_actions], "issued": issued, "reconciled": reconciled, } + # 普通使用者那一档另过一遍投影(口径身份不出去,人读的部分不动);builder 及以上拿原件 + return caliber_user_view(view) if ordinary else view async def report_labels(sealed: Any, report_node: str) -> dict[str, Any] | None: """一份报告里每个数的标签(遮过的),给证据片段接口和报告导出:{labels: {片段 id: 标签}, 来历}。没比对过、比对记录读不出、 - 这份报告没有标签的为 None(片段接口就不加 ledger 键,老运行的返回一字不差)。""" + 这份报告没有标签的为 None(片段接口就不加 ledger 键,老运行的返回一字不差)。 + + 普通使用者拿到的是投影过的那一份(口径身份不出去);builder 及以上是原件。""" + from app.api.deps import restricted + recorded = await store.latest(sealed.run_id) if recorded is None or recorded.content is None: return None @@ -203,8 +309,11 @@ async def report_labels(sealed: Any, report_node: str) -> dict[str, Any] | None: return None hider = await _hider(sealed) names = await _names(_workflow_ids(recorded.content)) - return {"labels": {sid: ledger_labels.view_label(label, hide=hider.hide, shown=hider.shown, names=names) - for sid, label in (report.get("labels") or {}).items()}, **_stamp(recorded)} + labels = {sid: ledger_labels.view_label(label, hide=hider.hide, shown=hider.shown, names=names) + for sid, label in (report.get("labels") or {}).items()} + if restricted(): + labels = {sid: label_user_view(label) for sid, label in labels.items()} + return {"labels": labels, **_stamp(recorded)} async def segment_label(sealed: Any, report_node: str, segment_id: str) -> dict[str, Any] | None: diff --git a/backend/app/look/calibers.py b/backend/app/look/calibers.py index 7be9ad8c..c940d649 100644 --- a/backend/app/look/calibers.py +++ b/backend/app/look/calibers.py @@ -1,8 +1,8 @@ """查看的对象之一:口径(normal-user-apps N2,补 G10:没有按名字检索的口径库)。蓝图助手看「看哪些数」时,先查数据目录, 再查已发布工作流里的口径卡:对到已有的口径卡时优先复用(实例化成 caliber_from),不重写指标式。 -只列每个工作流最新的「已发布且未退役」的版本(app/apps/versions,P5 的唯一说法)里的口径卡,本身转抄别处口径卡的 -(caliber_from)不列——源头才能复用(运行时也只认源头,engine/nodes/metrics._pinned_caliber)。 +只列每个工作流的**推荐发布版**(K07:Workflow.published_version,默认调用读它;最高已发布版只在升级发现里用)里的口径卡, +本身转抄别处口径卡的(caliber_from)不列——源头才能复用(运行时也只认源头,engine/nodes/metrics._pinned_caliber)。 复用的是整张卡(caliber_from 固定到那一版的那张卡),卡上每个指标都要算得出来:卡读的每个输入都要是 cell(nodes.X, 0, '列名')、X 是查库的调用工具节点。新图里那个库的取数节点就叫 X、交出同样的列(blueprints/templates/_common.data_groups)。 @@ -10,14 +10,27 @@ 点名写法:source 写工作流名(或 id),name 写指标名(或指标 id);只写 source 列那个工作流的全部指标。 -**问数据里**(compose=True,next-round 02 做法 4):同一套口径,另给每张卡的入口字段(类型、必填、可选值、格式、缺省值, -同 apps/describe 的写法)和「能不能组合」,能组合的写出 use_caliber 的写法;仍然不给 SQL(SQL 里可能写着遮罩值,组合 -时取数节点由服务端照抄,见 ledger/compose.py)。能不能组合由 ledger/derive.load_pinned 判(和对账、评测同一个认法), -读好的版本快照交给 GraphApplier(流里不碰库)。蓝图助手不走这一支,行为不变。 +**问数据里**(compose=True,next-round 02 做法 4):同一套口径,另给每张卡的入口字段、**能选用的指标**(每个指标这次要哪几个 +入口字段)和「能不能组合」,能组合的写出 use_caliber 的写法;仍然不给 SQL(SQL 里可能写着遮罩值,组合时取数节点由服务端照抄, +见 ledger/compose.py)。能不能组合 K08 S4 起按**每个指标**判(calibers.metric_options:依赖闭包加同一份「输入能不能复用」的 +判定):B 独有那条查询坏了、绑定对不上,只让 B 用不了,A 照旧给组合写法;一个可选指标也没有才标不能组合。这一层只是预筛、 +不改任何判断——真正选用时 ledger/compose.instantiate 按这次要算的指标逐项硬校验。读好的版本快照(derive.read_pinned,只读 +这一版、不判依赖)交给 GraphApplier,流里不碰库。蓝图助手不走这一支,行为不变。 + +**普通使用者只看得到有授权的口径(K14)。** 看这份清单的普通使用者(开登录后的 user 角色,`permitted_versions`)只列 +`apps/access.usable_calibers` 里那些「未归档应用的当前发布版精确固定着的」版本,别的连解析都不做——模型因此只会从它有授权的 +口径里挑,不会挑一个一调就被 QueryCore 拒的。builder / admin / 关登录不按这一层收窄(它们本来就能按口径执行),行为不变; +能不能执行最终还是 QueryCore 按同一份授权判(querycore 的 `_require_caliber`),这一层只是不让模型看见用不了的。 + +**问数据里的普通使用者**(`query=True`,K14)看的是同一份清单,但**没有 use_caliber**:那条路要把口径的取数节点(含 SQL) +拷进使用者的图里,只有搭建者及以上能走。这一档照样给**入口字段、能算哪些指标**(同一份 `metric_options`:安全,没有 SQL、 +没有参数值),再加上「在一个 agent 节点里照这一行调口径查询工具」的写法——使用者问的数因此来自一次固定口径执行,而不是自己 +拼一份差不多的 SQL。 """ from __future__ import annotations import json +from collections.abc import Iterable, Mapping from dataclasses import dataclass from typing import Any @@ -42,13 +55,25 @@ DETAIL_REUSE_PROMPT = (" 复用写法(「看哪些数」这一项的 reuse " 这张卡读:{inputs}。实例化时那个库的取数节点就叫这个名字、交出这几列,复用才算得出来") DETAIL_INPUT_PROMPT = "{node}({tool})的列 {columns}" DETAIL_NOT_REUSABLE_PROMPT = " 不能复用:{reason}。请按表重新对" -#: 问数据里(compose)每张卡写一次:入口字段、能不能组合 +#: 问数据里(compose)每张卡写一次:入口字段、能选用的指标、能不能组合 DETAIL_FIELDS_PROMPT = " 口径「{workflow}」v{version} 的入口字段:{fields}" DETAIL_FIELD_PROMPT = "{name}({bits}){desc}" DETAIL_NO_FIELDS_PROMPT = " 口径「{workflow}」v{version} 的入口没有字段" +#: 这次能选用的指标:每个写它要哪几个入口字段(K08 S4:按这次的选择闭包写,B 那条查询坏了只影响 B) +DETAIL_SELECTABLE_PROMPT = " 能选用的指标:{metrics}" +#: 这次用不了的指标:每个写一句原因。照实写出来,不让模型挑一个一选就被拒的 +DETAIL_UNAVAILABLE_PROMPT = " 用不了的指标:{metrics}" DETAIL_COMPOSE_PROMPT = (" 能组合:选用写法 {op}(card 原样照抄,是那一版图里口径卡的节点 id;id 自己起,生成的口径卡用它当节点 id;" - "inputs 按上面的入口字段填,没写的取缺省值;metrics 写要用的指标 id)") + "metrics 从上面能选用的指标里挑,写指标 id;inputs 只填选中的那几个指标要的字段——上面每个指标后面写了要哪些," + "没写的取缺省值)") DETAIL_NOT_COMPOSABLE_PROMPT = " 不能组合:{reason}。这份口径只能作为参考,查库交给 agent" +#: 普通使用者那一档(K14):这一档没有 use_caliber(那条路要把口径的取数 SQL 拷进图里),给的是「在一个 agent 节点里照 +#: 这一行调口径查询工具」的写法。口径身份、指标 id、inputs 照抄;工具自己读推荐版并当场固定,所以这里没有版本号 +DETAIL_QUERY_PROMPT = (" 取数写法(在 agent 节点的 prompt 里让它照这一行调用 {tool} 工具,不要自己写取数 SQL、" + "也不要照口径的 SQL 拼一份):{call}\n" + " 这里 workflow 写的是工作流 id,card 是口径卡的节点 id,照抄不要改;inputs 只填这次用得上的入口字段," + "相对时间(上个月、上周这类)先取当前日期再折算") +DETAIL_NO_QUERY_PROMPT = " 这一版没有能按 {tool} 算的指标:{reason}。要这个数就按表自己查" BRIEF_PROMPT = "· {name}({workflow} v{version}):字数超过上限,只列名字,要看指标式时点名再 look" MISSING_PROMPT = "没找到口径:{items}(只能查看已发布且未退役的版本里的口径卡;别拿名字相近的顶替)" INDEX_LINE_PROMPT = "{workflow}|{card}|{name}({metric})|{unit}" @@ -98,12 +123,62 @@ class CaliberView: "inputs": [{"node": n, "tool": t, "columns": list(cols)} for n, t, cols in self.inputs]} +def measured_inputs(nodes: Mapping[str, Any], metrics: Iterable[Any]) -> tuple[dict[str, dict[str, Any]], str | None]: + """这几个指标读的取数节点与列:{节点 id: {node, tool, columns}}(按第一次被读到的先后,列按出现先后去重)。 + + **每个输入都要**是 cell(nodes.X, 0, '列名')、X 是查库的调用工具节点:有一处不是就整份不收、给原因(不是查库结果里的 + 格 / 按别的行号取格,按卡上指标的先后取第一条不合规的)。整卡(card_inputs)与按指标(metric_inputs)都走这一份判定, + 不各写一遍。""" + from app.engine.expressions import ExpressionError, cell_parts, leaf_refs, parse_expression + from app.tools.datasource import QUERY_PREFIX + + found: dict[str, dict[str, Any]] = {} + for metric in metrics: + paths = _metric_paths(metric) + if paths is None: + return {}, NOT_TOOL_REASON + for path in paths: + try: + tree = parse_expression(path)[0] + except ExpressionError: + return {}, NOT_TOOL_REASON + for leaf in leaf_refs(tree): + parts = cell_parts(leaf) + if parts is None: + return {}, NOT_TOOL_REASON + chain, row, column = parts + node_id = chain[len("nodes."):] if chain.startswith("nodes.") else "" + tool = str((nodes.get(node_id) or {}).get("config", {}).get("tool") or "") + if (nodes.get(node_id) or {}).get("type") != "tool" or not tool.startswith(QUERY_PREFIX): + return {}, NOT_TOOL_REASON + if row.strip() != "0": + return {}, ROW_REASON + try: + col = json.loads(column.replace("'", '"')) if column[:1] in ("'", '"') else None + except ValueError: + col = None + if not isinstance(col, str): + return {}, NOT_TOOL_REASON + entry = found.setdefault(node_id, {"node": node_id, "tool": tool, "columns": []}) + if col not in entry["columns"]: + entry["columns"].append(col) + return found, None + + +def _card_node(graph: Mapping[str, Any], card_id: str) -> dict[str, Any] | None: + """图里那张口径卡;不是口径卡(或本身是转抄卡)时给不出可复用的输入。""" + from app.apps.tree import node_map + + card = node_map(graph).get(card_id) + if card is None or card["type"] != "metrics" or card["config"].get("caliber_from") not in (None, "", {}): + return None + return card + + def card_inputs(graph: dict[str, Any], card_id: str) -> tuple[list[dict[str, Any]], str | None]: """整张口径卡读的取数节点和列:([{node, tool, columns}], 不能复用的原因)。每个指标式的每个输入都要是 cell(nodes.X, 0, '列名')、X 是查库的调用工具节点(engine/lineage 认的原始数据,且只取第一行)。""" from app.apps.tree import node_map - from app.engine.expressions import ExpressionError, cell_parts, leaf_refs, parse_expression - from app.tools.datasource import QUERY_PREFIX nodes = node_map(graph) card = nodes.get(card_id) @@ -111,37 +186,74 @@ def card_inputs(graph: dict[str, Any], card_id: str) -> tuple[list[dict[str, Any return [], "指的不是口径卡" if card["config"].get("caliber_from") not in (None, "", {}): return [], CHAINED_REASON - found: dict[str, dict[str, Any]] = {} - for metric in card["config"].get("metrics") or []: - paths = _metric_paths(metric) - if paths is None: - return [], NOT_TOOL_REASON - for path in paths: - try: - tree = parse_expression(path)[0] - except ExpressionError: - return [], NOT_TOOL_REASON - for leaf in leaf_refs(tree): - parts = cell_parts(leaf) - if parts is None: - return [], NOT_TOOL_REASON - chain, row, column = parts - node_id = chain[len("nodes."):] if chain.startswith("nodes.") else "" - tool = str((nodes.get(node_id) or {}).get("config", {}).get("tool") or "") - if (nodes.get(node_id) or {}).get("type") != "tool" or not tool.startswith(QUERY_PREFIX): - return [], NOT_TOOL_REASON - if row.strip() != "0": - return [], ROW_REASON - try: - col = json.loads(column.replace("'", '"')) if column[:1] in ("'", '"') else None - except ValueError: - col = None - if not isinstance(col, str): - return [], NOT_TOOL_REASON - entry = found.setdefault(node_id, {"node": node_id, "tool": tool, "columns": []}) - if col not in entry["columns"]: - entry["columns"].append(col) - return list(found.values()), None + found, reason = measured_inputs(nodes, card["config"].get("metrics") or []) + return (list(found.values()), None) if reason is None else ([], reason) + + +def metric_inputs(graph: dict[str, Any], card_id: str, metric: Any) -> tuple[list[dict[str, Any]], str | None]: + """一个指标读的取数节点和列(判定与 card_inputs 同一份 measured_inputs):([{node, tool, columns}], 原因)。 + + look 的按指标可组合性(metric_options)用它:B 那条查询读不出格,不影响 A 那条。""" + from app.apps.tree import node_map + + card = _card_node(graph, card_id) + if card is None: + return [], "指的不是口径卡" + found, reason = measured_inputs(node_map(graph), [metric]) + return (list(found.values()), None) if reason is None else ([], reason) + + +@dataclass(frozen=True) +class MetricOptions: + """一张源头口径卡这一版**按指标**的可组合性(K08 S4):整卡那一份闭包的摘要 + 每个指标能不能选。 + + ``default`` / ``default_reason`` 是「不点名、算整卡」那一份(能算就给摘要,算不出来就给原因);``selectable`` 与 + ``unavailable`` 按**源卡顺序**。摘要里只有 query_id、节点、工具、入口字段、指纹与共享声明(computes_unselected), + **没有 SQL 正文、没有参数值**。""" + + default: dict[str, Any] | None + default_reason: str | None + selectable: tuple[dict[str, Any], ...] + unavailable: tuple[dict[str, Any], ...] + + @property + def composable(self) -> bool: + return bool(self.selectable) + + +def metric_options(graph: Mapping[str, Any], card_id: str, *, workflow_id: str, version: int) -> MetricOptions: + """这张源头口径卡上每个指标**单独点名**能不能选(K08 S4)。判据只有两条,都是既有那一份判定: + + ① 它读的输入能不能复用:每个输入都是 cell(nodes.X, 0, '列名')、X 是查库的调用工具节点(measured_inputs,与 + card_inputs 同一份);② 它的依赖闭包有没有未决(ledger/closure:式子读得出来、取数节点在、SQL 有、参数声明对得上、 + 绑定对得上)。不成立的进 unavailable 并写明原因——**B 独有那条查询坏了、绑定对不上,不影响 A**;A 和 B 共用一条 + SQL 时那条 SQL 按各自的选择照常保留,还在算谁记在 summary 的 computes_unselected 上。 + + 这里只是**预筛**(给模型看能不能组合、能选哪些指标):不改任何判断,真正选用时 ledger/compose.instantiate 按同一份 + 闭包逐项硬校验。同一张卡这一版算几次都一样。""" + from app.ledger import closure as caliber_closure + from app.ledger.derive import problems_text + + card = _card_node(graph, card_id) + if card is None: + return MetricOptions(None, "指的不是口径卡", (), ()) + metrics = [m for m in card["config"].get("metrics") or [] if isinstance(m, dict) and m.get("id")] + whole = caliber_closure.build(graph, workflow_id, version, card_id) # 不点名:整卡那一份 + selectable: list[dict[str, Any]] = [] + unavailable: list[dict[str, Any]] = [] + for metric in metrics: + metric_id, name = str(metric["id"]), str(metric.get("name") or metric["id"]) + _, reason = metric_inputs(graph, card_id, metric) + if reason is None: + one = caliber_closure.build(graph, workflow_id, version, card_id, metric_ids=[metric_id]) + if not one.unresolved: + selectable.append({"metric_id": metric_id, "name": name, **one.summary()}) + continue + reason = problems_text(one.unresolved) + unavailable.append({"metric_id": metric_id, "name": name, "reason": reason}) + return MetricOptions(whole.summary() if not whole.unresolved else None, + problems_text(whole.unresolved) if whole.unresolved else None, + tuple(selectable), tuple(unavailable)) def _metric_paths(metric: Any) -> list[str] | None: @@ -212,32 +324,63 @@ def field_text(f: dict[str, Any]) -> str: return DETAIL_FIELD_PROMPT.format(name=f.get("name"), bits=",".join(bits), desc=desc) +async def permitted_versions(session: Any, actor: Any = None) -> set[tuple[str, int]] | None: + """这个 actor 能用的口径版本(`(workflow_id, version)` 的集合);None 表示**不按资产授权收窄**。 + + None 是 builder / admin / 关登录(auth/chat_policy.restricted_actor 交回 False):它们本来就能按口径执行、也能自己 + 在画布上绑口径查询,这里不替它们收窄。普通使用者交回它有授权的那些版本(apps/access.usable_calibers:未归档应用的 + 当前发布版精确固定着这一版 + AppGrant 至少 use);一份也没有时是空集合,清单就是空的。`actor` 不给就取当前请求的身份。""" + from app.apps.access import usable_calibers + from app.auth.chat_policy import effective_actor, restricted_actor + + who = effective_actor(actor) + if not await restricted_actor(session, who): + return None + return {(str(workflow_id), int(version)) + for workflow_id, version in (await usable_calibers(session, who))} + + class CaliberKind: kind = "caliber" label = "口径" def __init__(self, items: list[CaliberView], *, picker: Picker | None = None, - options: list[Any] | None = None) -> None: + options: list[Any] | None = None, query: bool = False) -> None: self.items = items self.picker = picker - #: 问数据里(compose):每张卡能不能组合(ledger/compose.Option),没开组合时为 None + #: 问数据里(compose / query 两档):每张卡读好的那一份(入口字段、能算哪些指标、能不能组合),没读时为 None self.options = options + #: 问数据里**普通使用者**那一档(K14):不给 use_caliber(把口径的 SQL 拷进图),只给按口径查询工具取数的写法。 + #: use_caliber 能不能用看这个标记(api/copilot_context.composing):options 两档都读,差别只在怎么用 + self.query = query @classmethod - async def load(cls, session: Any, *, picker: Picker | None = None, compose: bool = False) -> CaliberKind: - """读每个工作流最新的已发布且未退役的版本里的口径卡。用调用方的会话,开流之前读好。compose:问数据里,另把每张卡 - 的那一版读好、判能不能组合(见模块说明)。""" + async def load(cls, session: Any, *, picker: Picker | None = None, compose: bool = False, + actor: Any = None, query: bool = False) -> CaliberKind: + """读每个工作流**推荐发布版**(Workflow.published_version,K07)里的口径卡。用调用方的会话,开流之前读好。 + compose:问数据里(搭建者及以上),另把每张卡的那一版读好、判能不能组合(见模块说明)。 + query:问数据里(普通使用者),读同一份数据、但只给按口径查询工具取数的写法(use_caliber 不开)。 + + 默认调用读推荐版(重新推上一版旧版之后默认就跟着它),最高已发布版只在升级发现里用(publications.upgrade_of); + purpose 是服务端入口常量:compose 表示这次是「组合式问数选用口径」,否则按探索(查看/给出)。`actor` 是这次是谁 + (Principal 或用户名,不给就取当前请求的身份):**普通使用者只列有授权的那些版本**(permitted_versions), + builder / admin / 关登录照旧列全部。""" from sqlalchemy import select - from app.apps import versions as app_versions + from app.apps import publications from app.db.models import Workflow + purpose = publications.PURPOSE_COMPOSE if (compose or query) else publications.PURPOSE_EXPLORE + permitted = await permitted_versions(session, actor) items: list[CaliberView] = [] for wf in (await session.execute(select(Workflow).order_by(Workflow.name, Workflow.id))).scalars().all(): - latest = await app_versions.latest_published(session, wf.id) - if latest is not None: - items += views_of(wf.id, wf.name, latest) - return cls(items, picker=picker, options=await _options(session, items) if compose else None) + if permitted is not None and not any(str(wf.id) == key[0] for key in permitted): + continue # 这个工作流一版也没授权给它:连推荐版都不解析 + resolved = await publications.resolve(session, wf, purpose=purpose) + if resolved is not None and (permitted is None or (str(wf.id), int(resolved.version)) in permitted): + items += views_of(wf.id, wf.name, resolved.row) + read = await _options(session, items) if (compose or query) else None + return cls(items, picker=picker, options=read, query=query) def option_of(self, item: CaliberView) -> Any | None: if self.options is None: @@ -332,7 +475,7 @@ class CaliberKind: block.append(DETAIL_DEFINITION_PROMPT.format(text=item.definition)) option = self.option_of(item) if option is not None: - block += _compose_lines(item, option, seen) + block += _query_lines(item, option, seen) if self.query else _compose_lines(item, option, seen) elif (reuse := item.reuse()) is not None: block.append(DETAIL_REUSE_PROMPT.format( reuse=json.dumps({k: v for k, v in reuse.items() if k != "inputs"}, ensure_ascii=False), @@ -365,10 +508,15 @@ class CaliberKind: async def _options(session: Any, items: list[CaliberView]) -> list[Any]: - """每张卡(工作流、版本、卡)读一次那一版、判能不能组合:ledger/derive.load_pinned(和对账、评测同一个认法),再看 - 取数 SQL 模板里的参数认不认得出写在哪(ledger/compose 校验参数要用)。""" - from app.ledger.compose import ComposeRefused, Option, _slot_contexts - from app.ledger.derive import NotDerivable, load_pinned + """每张卡(工作流、版本、卡)读一次那一版,按**每个指标**判能不能组合(K08 S4)。 + + 整卡那一道门禁不再先跑:B 独有那条查询坏了、绑定对不上、参数没声明,都只让 B 不可选,A 照旧给组合写法。可选哪些 + 指标、各自要哪些入口字段、不能选的为什么,写在 selectable_metrics / unavailable_metrics 上;一个指标也选不了才标 + 不能组合(原因照实给)。**这一层只是预筛**:真正选用时 ledger/compose.instantiate 按这次要算的指标逐项硬校验 + (未知指标、参数、绑定),不靠预筛的结论放宽。 + """ + from app.ledger import derive + from app.ledger.compose import Option out: list[Any] = [] for item in items: @@ -377,37 +525,107 @@ async def _options(session: Any, items: list[CaliberView]) -> list[Any]: base = {"workflow_id": item.workflow_id, "workflow_name": item.workflow_name, "version": item.version, "level": item.level, "node_id": item.node_id, "card": item.card} try: - pinned = await load_pinned(session, item.workflow_id, item.version, item.node_id) - _slot_contexts(pinned) - except NotDerivable as e: + pinned = await derive.read_pinned(session, item.workflow_id, item.version, item.node_id) + except derive.NotDerivable as e: out.append(Option(**base, reason=e.message)) continue - except ComposeRefused as e: - out.append(Option(**base, reason=e.message)) + made = metric_options(pinned.graph, pinned.node_id, workflow_id=pinned.workflow_id, version=pinned.version) + reason = option_reason(made) + if not made.composable: + out.append(Option(**base, reason=reason, unavailable_metrics=made.unavailable)) continue - out.append(Option(**base, pinned=pinned)) + out.append(Option(**base, pinned=pinned, reason=reason, selectable_metrics=made.selectable, + unavailable_metrics=made.unavailable, default_closure=made.default)) return out -def _compose_lines(item: CaliberView, option: Any, seen: set[tuple[str, int, str]]) -> list[str]: - """问数据里一张卡的入口字段和组合写法(同一张卡只写一次)。""" +def no_choice_reason(made: MetricOptions) -> str: + """一个指标也选不了时给模型的那句话:先说第一个指标为什么不行,实在没有就照整卡那份闭包的原因说。""" + if made.unavailable: + first = made.unavailable[0] + return f"「{first.get('name') or first.get('metric_id')}」{first.get('reason')}" + return made.default_reason or "这张卡这一版没有能选用的指标" + + +def option_reason(made: MetricOptions) -> str | None: + """这一版该给的那句「能不能组合」:能组合时是不点名(整卡)那一份算不出来的原因(能算出来就是 None), + 一个指标也选不了时是第一个指标的原因。列表接口、单条接口与问数据的选用选项用的是同一份。""" + return made.default_reason if made.composable else no_choice_reason(made) + + +def _card_fields(option: Any) -> list[dict[str, Any]]: + """这次能算的指标真正要用的入口字段(按声明顺序):入口字段只列用得上的那些,写法同 apps/describe。""" + needed = {str(name) for m in option.selectable_metrics for name in m["required_entry_fields"]} + return [f for f in option.pinned.entry_fields if str(f.get("name")) in needed] + + +def _query_lines(item: CaliberView, option: Any, seen: set[tuple[str, int, str]]) -> list[str]: + """普通使用者那一档(K14):一张卡的入口字段、能算的指标和**按口径查询工具取数**的写法(同一张卡只写一次)。 + + 和 `_compose_lines` 的差别只有最后一行:那条路是 use_caliber(服务端把口径的取数节点拷进图里),这一条是模型在一个 + agent 节点里调口径查询工具(工具自己读推荐版并当场固定,所以写法里没有版本号)。两档都不给 SQL、不给参数值。""" + from app.ledger.querycore import CALIBER_QUERY + key = (item.workflow_id, item.version, item.node_id) if key in seen: return [] seen.add(key) if not option.composable: - return [DETAIL_NOT_COMPOSABLE_PROMPT.format(reason=option.reason)] - fields = [f for f in option.pinned.entry_fields if f.get("name")] + return [DETAIL_NO_QUERY_PROMPT.format(tool=CALIBER_QUERY, + reason=option.reason or "这张卡这一版没有能算的指标")] + fields = _card_fields(option) lines = [DETAIL_FIELDS_PROMPT.format(workflow=item.workflow_name, version=item.version, fields=";".join(field_text(f) for f in fields)) if fields else DETAIL_NO_FIELDS_PROMPT.format(workflow=item.workflow_name, version=item.version)] + lines.append(DETAIL_SELECTABLE_PROMPT.format(metrics=metric_briefs(option.selectable_metrics))) + if option.unavailable_metrics: + lines.append(DETAIL_UNAVAILABLE_PROMPT.format(metrics=metric_briefs(option.unavailable_metrics))) + call = {"workflow": item.workflow_id, "card": item.node_id, + "metric_ids": [m["metric_id"] for m in option.selectable_metrics][:6], + "inputs": {str(f["name"]): "…" for f in fields}} + lines.append(DETAIL_QUERY_PROMPT.format(tool=CALIBER_QUERY, call=json.dumps(call, ensure_ascii=False))) + return lines + + +def _compose_lines(item: CaliberView, option: Any, seen: set[tuple[str, int, str]]) -> list[str]: + """问数据里一张卡的入口字段、能选用的指标和组合写法(同一张卡只写一次)。 + + K08 S4:能选哪些指标、各自要哪些入口字段按**这次的选择闭包**写(B 那条查询坏了只影响 B,共享 SQL 照常保留); + 用不了的指标连同原因照实写出来,不让模型挑一个一选就被拒的。摘要里没有 SQL、没有参数值。""" + key = (item.workflow_id, item.version, item.node_id) + if key in seen: + return [] + seen.add(key) + if not option.composable: + return [DETAIL_NOT_COMPOSABLE_PROMPT.format(reason=option.reason or "这张卡这一版没有能选用的指标")] + # 入口字段只列这次可选指标真正要用的那些(声明、类型、缺省值照 apps/describe 那个写法) + fields = _card_fields(option) + lines = [DETAIL_FIELDS_PROMPT.format(workflow=item.workflow_name, version=item.version, + fields=";".join(field_text(f) for f in fields)) + if fields else DETAIL_NO_FIELDS_PROMPT.format(workflow=item.workflow_name, version=item.version)] + lines.append(DETAIL_SELECTABLE_PROMPT.format(metrics=metric_briefs(option.selectable_metrics))) + if option.unavailable_metrics: + lines.append(DETAIL_UNAVAILABLE_PROMPT.format(metrics=metric_briefs(option.unavailable_metrics))) example = {"op": "use_caliber", "id": "c1", "workflow_id": item.workflow_id, "version": item.version, - "card": item.node_id, "metrics": [m["id"] for m in option.pinned.metrics][:6], + "card": item.node_id, "metrics": [m["metric_id"] for m in option.selectable_metrics][:6], "inputs": {str(f["name"]): "…" for f in fields}} lines.append(DETAIL_COMPOSE_PROMPT.format(op=json.dumps(example, ensure_ascii=False))) return lines +def metric_briefs(entries: Iterable[Mapping[str, Any]]) -> str: + """一行里一个指标一段:能选的写它要哪些入口字段,用不了的写原因(都不放 SQL 与参数值)。""" + out: list[str] = [] + for m in entries: + name, metric_id = str(m.get("name") or m.get("metric_id")), str(m.get("metric_id")) + if "required_entry_fields" in m: + need = [str(x) for x in m["required_entry_fields"]] + out.append(f"{name}({metric_id},要 {'、'.join(need)})" if need else f"{name}({metric_id},不用入口字段)") + else: + out.append(f"{name}({metric_id}):{m.get('reason')}") + return ";".join(out) or "无" + + async def verify_reuse(session: Any, ref: dict[str, Any]) -> dict[str, Any]: """蓝图存的时候按库里那一版核对复用的口径卡:已发布且未退役、是源头的口径卡、有这个指标、能复用。交回补上 inputs 的 reuse;不行抛 BpRefused(bp.data_unmapped)。用户在卡片上选的、助手提的都过这一道。""" diff --git a/backend/app/main.py b/backend/app/main.py index fe351e27..17d6f96e 100644 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -29,6 +29,8 @@ from app.api import ( ) # 编排完善第 1 波(docs/design/orchestration-round §1):问数据的一轮在服务端跑 from app.api import chat_turns as chat_turns_api +# 增量重导入(K11):建一次导入、看工作项和冲突、接受选定字段、拒绝、人工对齐、恢复 +from app.api import caliber_import as caliber_import_api from app.api.coded import CodedHTTPException, coded_handler from app.api.deps import chat_scope, evidence_scope, private_run_scope, require_role, role_by_method, run_scope from app.auth.keys import key_gate @@ -143,9 +145,10 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]: from app.chat import job as chat_job from app.eval import runner as eval_runner, snapshots as eval_snapshots - from app.ledger import jobs as draft_jobs + from app.ledger import jobs as draft_jobs, reimport as import_jobs await draft_jobs.manager.shutdown() + await import_jobs.manager.shutdown() await catalog_jobs.manager.shutdown() await catalog_profile_jobs.manager.shutdown() await introspect_jobs.manager.shutdown() @@ -246,7 +249,7 @@ def _register_reapers() -> None: from app.data import catalog_jobs, catalog_profile_jobs, introspect_jobs from app.eval import runner as eval_runner, snapshots as eval_snapshots from app.process import actions, tasks - from app.ledger import jobs as draft_jobs + from app.ledger import jobs as draft_jobs, reimport as import_jobs async def documents(live: Any) -> int: return await _reap_documents(live) @@ -255,6 +258,7 @@ def _register_reapers() -> None: ("运行", run_manager.reap), ("处理中的文档", documents), ("口径起草任务", lambda live: draft_jobs.startup(live=live)), + ("口径增量导入", lambda live: import_jobs.startup(live=live)), ("数据目录起草任务", lambda live: catalog_jobs.startup(live=live)), ("数据剖析任务", lambda live: catalog_profile_jobs.startup(live=live)), ("探查任务", lambda live: introspect_jobs.startup(live=live)), @@ -424,6 +428,8 @@ for router, guard in ( (shares_api.router, []), (notify_api.router, _USER), (ledger_api.router, _BUILDER), + # 增量重导入(K11):和 /api/ledger 其余写接口同一道门(搭建者);访问密钥不开放(不登记 KEY_ROUTES) + (caliber_import_api.router, _BUILDER), # 下一轮第 2 波:评测只给搭建者;访问密钥登录即可,接口里再按本人 / 管理员判 (evals_api.router, _BUILDER), # 口径账本里按答案出具、对账的(第 3 波):登录即可,接口里按运行和应用授权判 diff --git a/backend/app/records/views.py b/backend/app/records/views.py index 33460c5f..51d9e255 100644 --- a/backend/app/records/views.py +++ b/backend/app/records/views.py @@ -227,5 +227,21 @@ def cache_token(entry: Any) -> Any: return [entry.get("seq"), older] if older else entry.get("seq") +def inherit_scope(versions: dict[str, Any] | None) -> None: + """派生的子运行**继承**父 Run 已授权的 data_versions 时,记录表的行级范围原样带着,不重算(K10)。 + + 重算是错的:子运行按 exploratory 重算,一个正式父 Run 的 all 会被收成 mine/none——父已授权、子看得更少, + 同一次口径查询算出来的数就和父 Run 自己的不一样了;父 Run 发起之后管理员改了授权,同一次运行的前后两段 + 也会看到不同的行。范围在父 Run 发起时定下(records.access.scope_of_run),子运行既不放大也不缩小。 + 缺 rows 的项(升级前发起的运行、手工拼的)按最窄的 none 算,绝不当成 all。""" + from app.records.access import SCOPES + + for entry in (versions or {}).values(): + if not isinstance(entry, dict) or entry.get("origin") != RECORDS_ORIGIN: + continue + if entry.get("rows") not in SCOPES: + entry["rows"] = "none" + + def is_records(source: Any) -> bool: return (getattr(source, "origin", None) or "manual") == RECORDS_ORIGIN diff --git a/backend/app/tools/datasource.py b/backend/app/tools/datasource.py index 85abed0e..d7a43a91 100644 --- a/backend/app/tools/datasource.py +++ b/backend/app/tools/datasource.py @@ -38,6 +38,8 @@ from app.data.engine import SnapshotTampered, masked_columns, query_timeout, run from app.data.guard import QueryLimits, SqlRejected, check, is_write from app.data.tabular import UNSHAPED_NOTE from app.db.models import DataSource +from app.ledger.bindings import SNAPSHOT_KEY as CALIBER_BINDING_SNAPSHOT_KEY +from app.ledger.params import SNAPSHOT_KEY from app.tools.registry import ToolContext, Versions logger = logging.getLogger(__name__) @@ -57,6 +59,11 @@ LATE_PIN_CODE = "data_version_pinned" #: agent(engine/verify_agent.py)放进去,打开了遮罩开关的查询工具按它们按值遮,再把每次遮掉的值并进去。只在内存里给 #: 调用方按值遮用,不进快照、不交给模型 MASKED_VALUES_KEY = "masked_values" +#: 参数材料在 ToolContext.extra 里的键(就是 ledger/params.SNAPSHOT_KEY 的别名,engine/nodes/tools.run_tool 放,_run 读) +SQL_PARAMETERS_KEY = SNAPSHOT_KEY +#: K04 的绑定材料(ledger/bindings.SNAPSHOT_KEY 的别名,engine/nodes/tools.run_tool 放,_run 读):这条 SQL 是哪份 +#: 受控绑定的哪一次展开(业务值 + 绑定指纹),只在实际语句正好是它展开出来的时候才有 +CALIBER_BINDING_KEY = CALIBER_BINDING_SNAPSHOT_KEY #: 每次查询之后基于数据目录的 SQL 检查最多等这么久。正常一条 SQL 几毫秒;等不到就放弃这一次检查, #: 查询结果照常交回——检查是附加的,不能拖慢查询 @@ -743,7 +750,12 @@ def _make_query_tool(source: Any, ctx: ToolContext, *, fixed: bool = False, # - masked_whole:这条 SQL 的写法认不全,整份结果查询时都遮了(masked_at_query 是全部的列),格子引用指到它时 # 照实说写法认不全,不说成取自遮罩列; # - data_version:上传表格查的是哪个快照,事后据此认得出这个数出自哪一版数据。 - # 手工源、没设遮罩的,快照和原来一字不差 + # 以及(K01,ledger/params)参数材料:这条 SQL 来自哪份源模板(模板哈希;有正文的时候连正文一起——组合式 + # 问数拷进来的节点上不写正文,见 ledger/params.marker)、这次参数的规范化输入哈希、参数契约、每个参数的类型 + # 和写在 SQL 的哪儿、承载方式(内联文本替换,不是驱动绑定)。绑定值不另存一份——它就是内联进实际语句里的 + # 那些字,实际语句(payload["sql"])本身在快照里。没有参数的查询不写这一项,快照和原来一字不差 + # 以及(K04,ledger/bindings)绑定材料:这条 SQL 是哪份受控绑定的哪一次展开(业务值 + 绑定指纹), + # 只在实际语句正好是它展开出来的时候才有;没有绑定的取数照旧不写这一项 extra: dict[str, Any] = {} if mask: extra["mask_columns"] = mask @@ -755,6 +767,12 @@ def _make_query_tool(source: Any, ctx: ToolContext, *, fixed: bool = False, extra["masked_whole"] = True if version := getattr(source, "snapshot_id", None): extra["data_version"] = version + if material := (ctx.extra or {}).get(SQL_PARAMETERS_KEY): + extra["parameters"] = material + if binding_material := (ctx.extra or {}).get(CALIBER_BINDING_KEY): + # K04:这条 SQL 是哪份受控绑定的哪一次展开(binder/版本、业务域与映射版本、当时的业务值、绑定指纹)。 + # 只有实际语句正好是这份绑定展开出来的时候才记;不给模板和 snippets——实际语句本身就在快照里 + extra["binding"] = binding_material # 记录表(records/views.py):查的是第几条以内、看的是谁的行。不写进 data_version:那一项是上传表格的快照 # id,出处链按它找快照文件 if getattr(source, "origin", None) == "records" and getattr(source, "prelude", None): diff --git a/backend/app/tools/registry.py b/backend/app/tools/registry.py index 82d048c6..08d8c0c8 100644 --- a/backend/app/tools/registry.py +++ b/backend/app/tools/registry.py @@ -52,9 +52,39 @@ class ToolContext: #: 读哪一份数据目录(data/catalog_view.CatalogView):运行里由节点从 Run.options 取来(catalog_view.of_run),db_schema #: 给模型看的、查询冻结进表结构快照的、查询时的 SQL 检查都按它。None 是当前目录(缺省,行为同以前) catalog_view: Any = None + #: 这次运行的类别(formal / exploratory,engine/runner.py 从 Run.run_class 放进 RunContext.extra)。K10 的 + #: caliber_query 按它选用途:正式父 Run 走 formal judge,别的(交互、画布)走 compose、拿不到正式身份。None 按 + #: exploratory 算——宁可保守,也不把一次探索说成正式的 + run_class: str | None = None + #: 这次运行的发起人(服务端身份,同上)。caliber_query 拿它当执行的认证主体,不从工具参数里读 + started_by: str | None = None + #: 这次运行发起时定下的选项快照(Run.options,RunContext.extra 里那一份):caliber_query 照原样带进派生的子运行 + #: (遮罩、只读、数据目录视图……),不从工具参数里读 + run_options: dict[str, Any] = field(default_factory=dict) + #: 这次运行的来源(Run.origin,同上):caliber_query 把它当 trace 带下去,父子关系一眼看得全 + origin: dict[str, Any] | None = None extra: dict[str, Any] = field(default_factory=dict) +#: RunContext.extra 里的键(engine/runner.py 放、构造 ToolContext 的节点取):这次运行的类别、发起人与来源。 +#: 用途/主体/父 Run 关系由发起时定下,工具参数改不了(K10) +RUN_CLASS_KEY = "run_class" +RUN_STARTED_BY_KEY = "started_by" +RUN_ORIGIN_KEY = "origin" + + +def execution_id_of(node_id: str, *, attempt: int | None = None, call_id: str | None = None, + run_id: str | None = None) -> str: + """一次**实际执行**的执行身份(K10):`<运行>:<节点>#<调用 id 或执行序号>`。 + + 同一次运行里同一条 SQL 执行两次(agent 的两步、失败后接着跑)必须拿到不同的 execution_id——按调用 id(agent 的那 + 一步)或这个节点的执行序号(调用工具节点的第几次)区分。带上运行 id:口径查询派生的子运行每次调用都是一次新运行, + 同一个子节点在自己的运行里都是第 1 次——两次调用交回的工件来自两个子运行,执行身份也必须不同。 + query_id 是逻辑查询身份(K08 闭包那一条),execution_id 是这一次执行,两者不能互相当。""" + slot = str(call_id) if call_id else f"e{int(attempt or 1)}" + return f"{run_id}:{node_id}#{slot}" if run_id else f"{node_id}#{slot}" + + @dataclass(frozen=True) class ToolGuide: """绑了这个工具时一并交给模型的方法说明(写进 system,engine/nodes/llm.py 的 _build_messages、协作成员同样)。 @@ -125,6 +155,7 @@ def register( def all_specs() -> dict[str, ToolSpec]: import app.tools.builtin # noqa: F401 触发内置工具注册 + import app.ledger.querycore # noqa: F401 触发 caliber_query(K10 的父 Run 工具入口)注册 return dict(_REGISTRY) diff --git a/backend/tests/binding_samples.py b/backend/tests/binding_samples.py new file mode 100644 index 00000000..229d78db --- /dev/null +++ b/backend/tests/binding_samples.py @@ -0,0 +1,257 @@ +"""K04 的合成订单夹具:A/B/C/D 四单、一条受控模板 SQL、一张两个指标共享这条 SQL 的口径卡。 + +任务书 6.2 的正向样例(数据全是编的,和项目生产数据无关): + +| 订单 | 下单日期 | 支付日期 | 退款状态 | 金额 | +| --- | --- | --- | --- | --- | +| A | 2026-09-30 | 2026-10-02 | 未退款 | 100 | +| B | 2026-10-05 | 2026-11-01 | 未退款 | 200 | +| C | 2026-10-10 | 2026-10-10 | 全额退款 | 300 | +| D | 2026-10-20 | 2026-10-21 | 部分退款 | 400 | + +**旧定义**(按下单时间统计、不排除退款)十月 3 单 900 元:B、C、D。 +**新定义**(按支付时间统计、排除全额退款、保留部分退款)十月 2 单 500 元:A 纳入、B 跨期排除、C 排除、D 保留。 +两个指标(订单数、销售额)**共享同一条取数 SQL**:一条 SQL 上只能有一个时间口径,所以改定义必须两个指标的说法 +一致,才谈得上把 SQL 一起改过来。 + +取数是一个受控模板:`... WHERE ([[time_role]]) AND ([[refund_rule]])`,两个 token 展开成什么写在取数节点自己的 +`data.config.binding` 里(配置级、带版本,不是全局映射表)。夹具只负责把这些行、这份模板和这张卡摆出来, +判定和展开都在 app/ledger/bindings.py。 +""" +from __future__ import annotations + +import copy +import sqlite3 +import uuid +from collections.abc import Mapping +from typing import Any + +from app.core.artifact_store import graph_hash +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, DataSource, Workflow, WorkflowVersion +from app.ledger import bindings + +#: 四单:id、下单日期、支付日期、退款状态、金额 +ROWS = [("A", "2026-09-30", "2026-10-02", "none", 100.0), + ("B", "2026-10-05", "2026-11-01", "none", 200.0), + ("C", "2026-10-10", "2026-10-10", "full", 300.0), + ("D", "2026-10-20", "2026-10-21", "partial", 400.0)] + +#: 十月(半开区间)和九月各一个窗口:换窗口是请求变化,不建定义版本 +OCTOBER = {"start": "2026-10-01", "end": "2026-11-01"} +SEPTEMBER = {"start": "2026-09-01", "end": "2026-10-01"} + +#: 受控模板:两个业务 token 占位,别的都是常量;{{ input.* }} 仍归 K01,执行期照旧按入口渲染 +TEMPLATE = ("SELECT COUNT(*) AS orders, SUM(o.amount) AS amount FROM orders o " + "WHERE ([[time_role]]) AND ([[refund_rule]])") +SNIPPETS: dict[str, dict[str, str]] = { + "time_role": {"order_time": "o.ordered_at >= '{{ input.start }}' AND o.ordered_at < '{{ input.end }}'", + "payment_time": "o.paid_at >= '{{ input.start }}' AND o.paid_at < '{{ input.end }}'"}, + "refund_rule": {"include_all": "1 = 1", "exclude_full_refund": "o.refund_state <> 'full'"}, +} +OLD = {"time_role": "order_time", "refund_rule": "include_all"} +NEW = {"time_role": "payment_time", "refund_rule": "exclude_full_refund"} + +#: 独立预期(不来自任何一次执行):十月,旧定义 3 单 900 元,新定义 2 单 500 元 +EXPECTED = {"old": {"orders": 3, "amount": 900.0}, "new": {"orders": 2, "amount": 500.0}} + +#: 复杂 SQL 反例:CTE + 窗口函数算出来的东西,时间条件写死在里头——受控模板认不出落点, +#: 不是「字符串替换一下就行」的那种(改它要人先拿主意) +COMPLEX_SQL = ("WITH paid AS (SELECT id, ordered_at, paid_at, refund_state, amount, " + "ROW_NUMBER() OVER (PARTITION BY id ORDER BY paid_at DESC) AS rn " + "FROM orders WHERE paid_at IS NOT NULL) " + "SELECT COUNT(*) AS orders, SUM(amount) AS amount FROM paid " + "WHERE rn = 1 AND paid_at >= '2026-10-01' AND paid_at < '2026-11-01' " + "AND ([[refund_rule]])") + +#: 这个夹具里数据源的名字(fresh_source 换):图里的查询工具是 db_query__<它> +CURRENT = {"source": "orders"} +#: fresh_source 起过的数据源名:用例结束由测试的清理 fixture 删掉,不给别的用例留行 +MADE: dict[str, list[str]] = {"sources": []} + +__all__ = ["COMPLEX_SQL", "CURRENT", "EXPECTED", "NEW", "OCTOBER", "OLD", "ROWS", "SEPTEMBER", "SNIPPETS", + "TEMPLATE", "binding", "build_order_db", "card_metrics", "chained_graph", "complex_graph", "draft", + "fresh_source", "graph", "publish", "render", "tool", "upstream"] + + +def tool() -> str: + return f"db_query__{CURRENT['source']}" + + +def render(values: dict[str, str] = OLD) -> str: + """这份模板按业务值展开出来的 SQL(夹具里用同一个函数,和服务端判定的是同一份写法)。""" + return bindings.render(TEMPLATE, SNIPPETS, values) + + +def build_order_db(path) -> None: + db = sqlite3.connect(path) + db.executescript("CREATE TABLE orders (id TEXT PRIMARY KEY, ordered_at TEXT, paid_at TEXT, " + "refund_state TEXT, amount REAL);") + db.executemany("INSERT INTO orders VALUES (?, ?, ?, ?, ?)", ROWS) + db.commit() + db.close() + + +async def fresh_source(path) -> str: + """建库、起一个这个用例专用的数据源(名字不重复),返回数据源名。""" + build_order_db(path) + CURRENT["source"] = f"orders_{uuid.uuid4().hex[:8]}" + async with SessionLocal() as session: + session.add(DataSource(name=CURRENT["source"], kind="sqlite", database=str(path), readonly=True, + enabled=True)) + await session.commit() + MADE["sources"].append(CURRENT["source"]) + return CURRENT["source"] + + +def binding(values: dict[str, str] = OLD, *, domain: str = "order_sales", mapping_version: int = 1, + template: str = TEMPLATE, snippets: dict[str, dict[str, str]] | None = None, + sql: str | None = None, version: int = bindings.BINDER_VERSION, + binder: str = bindings.BINDER) -> dict[str, Any]: + """取数节点上的受控绑定(形状见 ledger/bindings)。""" + snippets = SNIPPETS if snippets is None else snippets + rendered = sql if sql is not None else bindings.render(template, snippets, values) + return {"binder": binder, "version": version, "domain": domain, "mapping_version": mapping_version, + "template": template, "snippets": copy.deepcopy(snippets), "values": copy.deepcopy(values), + "rendered_hash": bindings.sql_hash(rendered)} + + +def node(nid: str, ntype: str, **config: Any) -> dict[str, Any]: + return {"id": nid, "type": ntype, "position": {"x": 0, "y": 0}, "data": {"label": nid, "config": config}} + + +def chain(*nodes: dict[str, Any]) -> dict[str, Any]: + return {"nodes": list(nodes), "edges": [{"source": a["id"], "target": b["id"]} for a, b in zip(nodes, nodes[1:])]} + + +def card_metrics(time_role: str | None = OLD["time_role"], refund_rule: str | None = OLD["refund_rule"], + **_extra: Any) -> list[dict[str, Any]]: + """两个共享同一条 SQL 的指标:订单数、销售额。业务字段按参数写进去(None 表示不声明,走旧资产那条路)。""" + out = [] + for mid, name, column in (("m1", "订单数", "orders"), ("m2", "销售额", "amount")): + metric: dict[str, Any] = {"id": mid, "name": name, "unit": "单" if mid == "m1" else "元", + "decimals": 0, "expression": f"cell(nodes.fetch, 0, '{column}')", + "definition": {"text": f"{name}按业务口径统计"}} + if time_role: + metric["time_role"] = time_role + if refund_rule: + metric["refund_rule"] = refund_rule + out.append(metric) + return out + + +def graph(*, values: dict[str, str] = OLD, sql: str | None = None, metrics: list[dict[str, Any]] | None = None, + with_binding: bool = True, fields: list[dict[str, Any]] | None = None, + node_config: dict[str, Any] | None = None, source: str | None = None) -> dict[str, Any]: + """这张卡:入口 → 取数(带受控绑定)→ 口径卡 → 出口。同样的参数永远得到同一张图。 + + 不给 metrics 时,指标声明的时间口径和退款规则就按 values 写——一份**自洽**的定义:定义说支付时间,SQL 也就是 + 支付时间那份展开(v1 和 v2 各自自洽)。要构造「定义和实现对不上」的图,显式传 metrics。 + """ + sql = render(values) if sql is None else sql + metrics = (card_metrics(time_role=values.get("time_role"), refund_rule=values.get("refund_rule")) + if metrics is None else copy.deepcopy(metrics)) + fields = fields if fields is not None else [ + {"name": "start", "type": "string", "required": True, "description": "开始日期(含)"}, + {"name": "end", "type": "string", "required": True, "description": "结束日期(不含)"}] + config: dict[str, Any] = {"tool": f"db_query__{source or CURRENT['source']}", "args": {"sql": sql}, + "hints": {"keep": "me"}} + if with_binding: + config[bindings.KEY] = binding(values, sql=sql) + config.update(copy.deepcopy(node_config or {})) + return chain(node("start", "input", fields=fields), + node("fetch", "tool", **config), + node("card", "metrics", caliber="订单口径", caliber_version="v1", metrics=metrics), + node("out", "output", fields=[{"name": "结果", "value": "{{ nodes.card.text }}"}]), + ) + + +def complex_graph(*, values: dict[str, str] | None = None, metrics: list[dict[str, Any]] | None = None) -> dict: + """复杂 SQL 反例:时间条件写死在 CTE 里,绑定里只有 [[refund_rule]] 的落点。 + + 指标照样声明 time_role=payment_time——这正是「定义改了,但这条 SQL 表示不了它」的那种改动。 + """ + values = {"refund_rule": (values or OLD)["refund_rule"]} + sql = bindings.render(COMPLEX_SQL, SNIPPETS, values) + made = graph(values={**values, "time_role": "payment_time"}, sql=sql, metrics=metrics) + config = made["nodes"][1]["data"]["config"] + config[bindings.KEY] = binding(values, template=COMPLEX_SQL, snippets={"refund_rule": SNIPPETS["refund_rule"]}, + sql=sql) + return made + + +async def publish(graph: dict[str, Any], *, name: str = "K04 订单口径", level: str = "published") -> str: + """建一个已发布的(未退役)工作流 v1:口径描述接口只认已发布的那一版。返回工作流 id。""" + workflow_id = f"wf-{uuid.uuid4().hex[:12]}" + async with SessionLocal() as session: + session.add(Workflow(id=workflow_id, name=name, status="published", graph=copy.deepcopy(graph), + version=1, published_version=1)) + session.add(WorkflowVersion(workflow_id=workflow_id, version=1, graph=copy.deepcopy(graph), + graph_hash=graph_hash(graph), level=level)) + await session.commit() + return workflow_id + + +async def upstream(*, name: str | None = None) -> dict[str, Any]: + """一个上游工作流:v1 按下单时间、不排除退款(旧),v2 按支付时间 + 排除全额退款(新,定义和 SQL 已同步)。 + + 消费侧固定 v2 时,独立预期就是新定义的 2 单 500 元;本地那句取数要是还停在旧写法,跑出来的 3 单 900 元就是在 + 拿旧数冒充新定义。交回 {workflow_id, name, v1, v2, card}。 + """ + workflow_id = f"wf-{uuid.uuid4().hex[:12]}" + name = name or f"K04 上游订单口径 {uuid.uuid4().hex[:4]}" + old, new = graph(values=OLD), graph(values=NEW) + async with SessionLocal() as session: + session.add(Workflow(id=workflow_id, name=name, status="published", graph=copy.deepcopy(new), + version=2, published_version=2)) + for number, made in ((1, old), (2, new)): + session.add(WorkflowVersion(workflow_id=workflow_id, version=number, graph=copy.deepcopy(made), + graph_hash=graph_hash(made), level="published")) + await session.commit() + return {"workflow_id": workflow_id, "name": name, "v1": old, "v2": new, "card": "card"} + + +def chained_graph(pinned: Mapping[str, Any], *, version: int, local_values: dict[str, str] = OLD, + local_sql: str | None = None, rename: Mapping[str, str] | None = None) -> dict[str, Any]: + """消费侧的图:取数节点是本地的(可以还停在上游的旧写法上),口径卡 caliber_from 固定到上游的某一版。 + + rename 是 caliber_from.nodes 的源→本地映射({上游节点 id: 本地节点 id}):本地取数节点的 id 换成映射里的那个 + 名字,式子照上游写(nodes.fetch),判定和运行时都按映射落到本地节点上。 + """ + local_id = next(iter(dict(rename or {}).values()), "fetch") + sql = local_sql if local_sql is not None else render(local_values) + source: dict[str, Any] = {"workflow_id": pinned["workflow_id"], "workflow_version": version, + "node_id": pinned["card"]} + if rename: + source["nodes"] = dict(rename) + return chain(node("start", "input", fields=[ + {"name": "start", "type": "string", "required": True, "description": "开始日期(含)"}, + {"name": "end", "type": "string", "required": True, "description": "结束日期(不含)"}]), + node(local_id, "tool", tool=tool(), args={"sql": sql}, + **{bindings.KEY: binding(local_values, sql=sql)}), + node("card", "metrics", caliber_from=source), + node("out", "output", fields=[{"name": "结果", "value": "{{ nodes.card.text }}"}])) + + +async def draft(graph: dict[str, Any], *, name: str = "K04 订单口径", payload: dict[str, Any] | None = None, + tags: list[str] | None = None) -> dict[str, Any]: + """一份已接管到工作流上的草稿(docattach 那种产物:tags 有 doc_draft、origin 里没有 kind)。 + + 交回 {id, workflow_id, revision, card_id}:写入(PATCH operations)和试跑都用它。tags 传别的就是「不是已接管 + 的资产」,用来看旧路径。 + """ + workflow_id = f"wf-{uuid.uuid4().hex[:12]}" + draft_id = uuid.uuid4().hex[:32] + async with SessionLocal() as session: + session.add(Workflow(id=workflow_id, name=name, status="draft", graph=copy.deepcopy(graph), version=1, + tags=["doc_draft"] if tags is None else list(tags), + origin={"run_id": "run-1", "freeze": True, "sources": [{"run_id": "run-1"}]})) + session.add(WorkflowVersion(workflow_id=workflow_id, version=1, graph=copy.deepcopy(graph), + graph_hash=graph_hash(graph))) + await session.flush() + session.add(CaliberDraft(id=draft_id, title=name, status="ready", workflow_id=workflow_id, + payload={"version": 1, "workflow_id": workflow_id, + "metrics": copy.deepcopy(graph["nodes"][2]["data"]["config"]["metrics"]), + **(payload or {})})) + await session.commit() + return {"id": draft_id, "workflow_id": workflow_id, "revision": 1, "card_id": "card"} diff --git a/backend/tests/publication_samples.py b/backend/tests/publication_samples.py new file mode 100644 index 00000000..729d83e9 --- /dev/null +++ b/backend/tests/publication_samples.py @@ -0,0 +1,174 @@ +"""K07 发布依据与用途判定测试共用的帮手:建一份「已接管」的口径资产、放下验证记录与审阅、按入口发布。 + +资产的形状就是文档起草建出来的那种(tags=["doc_draft"],app/apps/versions.taken_over):一张源头口径卡 `card`、 +一个取数节点 `fetch`(查虚构店铺库)、一张口径「周销售」。验证记录和审阅走 K05 的真实落库入口 +(app/ledger/validation.append、app/ledger/review.decide),发布走真实的发布入口(HTTP 发布接口 / commit_publish), +不手写行、不伪造历史。 +""" +from __future__ import annotations + +import asyncio +import uuid +from typing import Any + +from httpx import AsyncClient +from sqlalchemy import select + +from app.core.artifact_store import graph_hash +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, Run, Workflow, WorkflowPublication, WorkflowVersion +from app.ledger import review as ledger_review +from app.ledger import validation +from tests import ledger_samples as S + +CARD = "card" +#: 人工确认过的独立期望(K05 的 expectation:来源 + 逐条给全卡指标) +EXPECTATION = {"source": "human_confirmed", "metrics": {"gmv": 2}, "note": "独立核算:十月两单"} + + +async def make_workflow(*, graph: dict | None = None, tags: list[str] | None = None, version: int = 1) -> dict: + """建一份口径资产(工作流 + v1 快照 + 一份草稿行),还没发布。tags 缺省是文档起草的产物(已接管)。""" + graph = graph or S.caliber_graph() + async with SessionLocal() as session: + workflow = Workflow(name=f"周销售-{uuid.uuid4().hex[:6]}", graph=graph, status="draft", + tags=tags if tags is not None else ["doc_draft"], version=version) + session.add(workflow) + await session.flush() + session.add(WorkflowVersion(workflow_id=workflow.id, version=version, graph=graph, + graph_hash=graph_hash(graph), note="从业务文档分组生成")) + draft = CaliberDraft(title="周销售口径草稿", workflow_id=workflow.id, status="ready") + session.add(draft) + await session.commit() + return {"workflow_id": workflow.id, "draft_id": draft.id, "graph": graph, "version": version} + + +async def add_version(asset: dict, graph: dict, *, version: int, note: str = "改过") -> dict: + """加一版(图上改了东西之后的保存结果),并把工作流当前版本推上去。""" + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + workflow.graph = graph + workflow.version = version + session.add(WorkflowVersion(workflow_id=workflow.id, version=version, graph=graph, + graph_hash=graph_hash(graph), note=note)) + await session.commit() + return {**asset, "graph": graph, "version": version} + + +async def add_record(asset: dict, *, graph: dict | None = None, card_id: str = CARD, status: str = "matched", + metric_ids: tuple[str, ...] = ("gmv",), version: int | None = None) -> str: + """按 K05 的落库入口追加一条验证记录。返回记录 id。""" + graph = graph or asset["graph"] + materials = validation.materials(graph, card_id, workflow_id=asset["workflow_id"]) + record_id = await validation.append( + draft_id=asset["draft_id"], workflow_id=asset["workflow_id"], version=version or asset["version"], + card_id=card_id, metric_ids=list(metric_ids), basis=materials, inputs={"start": "2026-10-01"}, + inputs_hash="inputs-1", trial_id=uuid.uuid4().hex, run_id="", actor="试跑人", status=status, problems=[], + expectation=EXPECTATION if status == "matched" else None, + actual={mid: {"value": 2, "status": "ok"} for mid in metric_ids}) + assert record_id, "验证记录没落下" + return record_id + + +async def confirm(asset: dict, record_id: str, *, scope: list[str] | None = None, verified: bool = True, + decision: str = "confirmed") -> str: + """按 K05 的审阅入口追加一条决定(主体、范围、所审依据)。返回决定 id。""" + async with SessionLocal() as session: + record = await validation.get_record(session, asset["draft_id"], record_id) + row = await ledger_review.decide(session, draft_id=asset["draft_id"], record=record, decision=decision, + actor="审核人", verified=verified, scope=scope, note="看过了") + await session.commit() + return row.id + + +async def publish(client: AsyncClient, asset: dict, *, version: int | None = None, level: str = "published") -> dict: + """走 HTTP 发布接口(唯一的发布入口最终都到这里)。""" + body = {"level": level, "version": version or asset["version"]} + res = await client.post(f"/api/workflows/{asset['workflow_id']}/publish", json=body, + headers={"X-Actor": "%E5%B0%8F%E7%8E%8B"}) + assert res.status_code == 200, res.text + return res.json() + + +async def events_of(workflow_id: str, version: int | None = None) -> list[WorkflowPublication]: + from app.apps import publications + + async with SessionLocal() as session: + return await publications.events(session, workflow_id, version) + + +async def latest_event(workflow_id: str, version: int) -> WorkflowPublication: + from app.apps import publications + + async with SessionLocal() as session: + row = await publications.latest(session, workflow_id, version) + assert row is not None, f"「{workflow_id}」v{version} 没有发布事件" + return row + + +async def persisted(workflow_id: str) -> Workflow: + async with SessionLocal() as session: + return await session.get(Workflow, workflow_id) + + +async def version_row(workflow_id: str, version: int) -> WorkflowVersion: + async with SessionLocal() as session: + return (await session.execute(select(WorkflowVersion).where( + WorkflowVersion.workflow_id == workflow_id, WorkflowVersion.version == version))).scalar_one() + + +def report_model(monkeypatch) -> None: + """假模型:图里那张报告节点(指令「写周销售」)引用口径卡的指标,别的照旧。正式运行才跑得完。""" + from langchain_core.messages import AIMessage + + from app.providers import mock_model + + def decide(self, messages): + text = "\n".join(str(getattr(m, "content", "")) for m in messages) + return AIMessage(content="周销售 [[m:gmv]]。" if "写周销售" in text else "这周的两单") + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", decide) + + +async def launch_formal(asset: dict, *, version: int | None = None, actor: str = "发布人", + input_payload: dict[str, Any] | None = None, origin_kind: str | None = "launcher") -> Run: + """从已发布的版本发起一次正式运行(engine/launch.launch_run:正式身份的唯一入口)。""" + from app.engine.launch import launch_run + + async with SessionLocal() as session: + return await launch_run(session, workflow_id=asset["workflow_id"], run_class="formal", + version=version or asset["version"], actor=actor, + input_payload=input_payload or {"start": "2026-09-01", "end": "2026-09-08"}, + origin_kind=origin_kind) + + +async def wait_run(run_id: str, timeout: float = 20.0) -> Run: + """等一次运行跑到终态(测试收尾不留挂着的任务)。""" + for _ in range(int(timeout / 0.05)): + async with SessionLocal() as session: + row = await session.get(Run, run_id) + if row.status in ("succeeded", "failed", "cancelled") and row.manifest_seq is not None: + return row + await asyncio.sleep(0.05) + raise AssertionError(f"运行 {run_id} 没有结束:{row.status}") + + +def publication_of(run: Run) -> dict[str, Any]: + """运行来源里记下的发布依据(K07:正式运行固定了哪一版、哪份清单、什么身份)。""" + origin = run.origin if isinstance(run.origin, dict) else {} + return origin.get("publication") or {} + + +async def issue_plan(session: Any, asset: dict, *, version: int | None = None) -> Any: + """按口径出具这一次的打算(走 K07 那条预检 ledger/issue.check_target,builder 身份)。""" + from app.api.deps import Principal + from app.ledger import issue as ledger_issue + from app.ledger.labels import caliber_key + + number = version or asset["version"] + workflow = await session.get(Workflow, asset["workflow_id"]) + plan = ledger_issue.Plan(run_id="source-run", workflow_id=asset["workflow_id"], version=number, + caliber=caliber_key(asset["workflow_id"], number)) + await ledger_issue.check_target(session, plan, workflow, + principal=Principal(username="boss", role="builder", mode="off", via="off"), + source_run="source-run") + return plan diff --git a/backend/tests/test_architecture_lifecycle.py b/backend/tests/test_architecture_lifecycle.py index 63ab935c..13c854ca 100644 --- a/backend/tests/test_architecture_lifecycle.py +++ b/backend/tests/test_architecture_lifecycle.py @@ -53,15 +53,18 @@ async def test_layout_save_keeps_trial_evidence_but_sql_change_invalidates(clien async with SessionLocal() as session: workflow = await session.get(Workflow, body["workflow_id"]) graph = copy.deepcopy(workflow.graph) + revision = workflow.version graph["nodes"][0]["position"] = {"x": 100, "y": 200} - saved = await client.patch(f"/api/workflows/{body['workflow_id']}", json={"graph": graph}) + saved = await client.patch(f"/api/workflows/{body['workflow_id']}", + json={"graph": graph, "expected_revision": revision}) assert saved.status_code == 200 assert saved.json()["same_as_published"] is True result = (await client.get(f"/api/ledger/drafts/{body['id']}/trial")).json() assert result["status"] == "succeeded" and result["version"] == 1 fetch = next(n for n in graph["nodes"] if n["id"] == "fetch") fetch["data"]["config"]["args"]["sql"] = "SELECT 9 AS refund_rate FROM orders" - changed = await client.patch(f"/api/workflows/{body['workflow_id']}", json={"graph": graph}) + changed = await client.patch(f"/api/workflows/{body['workflow_id']}", + json={"graph": graph, "expected_revision": saved.json()["version"]}) assert changed.json()["same_as_published"] is False result = (await client.get(f"/api/ledger/drafts/{body['id']}/trial")).json() assert result["status"] == "stale" and result["metrics"] == [] diff --git a/backend/tests/test_blueprint_generation.py b/backend/tests/test_blueprint_generation.py index b0fb23c1..72e24d33 100644 --- a/backend/tests/test_blueprint_generation.py +++ b/backend/tests/test_blueprint_generation.py @@ -231,7 +231,9 @@ async def test_look_caliber_lists_published_cards_and_how_to_reuse(): assert [(i.metric_id, i.name, i.version) for i in mine] == [("gmv", "销售额", 1), ("aov", "客单价", 1)] assert mine[1].reuse() == {"workflow_id": wf_id, "version": 1, "node_id": "kpi", "metric_id": "aov", "inputs": [{"node": "fetch", "tool": "db_query__shop", "columns": ["gmv", "order_cnt"]}]} - assert any(wf_name in line for line in await kind.overview()) + # 概览一行一个工作流、最多列 30 个(OVERVIEW_WORKFLOWS):测试会话共用一个库,积累多了这一个不一定排得进前 + # 30 行,所以按**点名的那一份**看它确实在清单里(index 列的是全部,不收窄) + assert wf_name in await kind.index([wf_name]) looks = LookService([kind]) result = await looks.look({"op": "look", "need": "客单价", "targets": [ {"kind": "caliber", "source": wf_name, "name": "客单价"}, {"kind": "caliber", "name": "不存在的指标"}]}, diff --git a/backend/tests/test_caliber_access.py b/backend/tests/test_caliber_access.py new file mode 100644 index 00000000..b89c18dd --- /dev/null +++ b/backend/tests/test_caliber_access.py @@ -0,0 +1,313 @@ +"""口径资产授权(apps/access.usable_calibers / caliber_role / caliber_granting_app):普通使用者「我能按哪些口径用」看的是 +应用授权,不是角色。 + +- 授权就是同一张 AppGrant:给本人、给他所在的组、给所有人,至少 use; +- 对象是应用**当前发布版**固定下来的那一版口径(AppVersion.pins,工作流和版本都精确对上),归档的应用不算、草稿里的固定不算; +- 同一版取最高档(use / observe / manage); +- 没有主体(actor 为空、用户名为空)、人停用、没有授权都是 None; +- builder / admin / 关登录**不在**这两个函数里自动放行:由调用方决定(ledger/issue.check_target 先显式放行搭建者及以上, + 使用者才走这份判定)。 + +测试会话共用一个临时库,别的工作流、应用留下的行都在:断言只按这个用例自己的 (workflow_id, version) 和用户名看。 +""" +from __future__ import annotations + +import uuid + +from app.api.deps import Principal +from app.apps.access import caliber_granting_app, caliber_role, usable_calibers +from app.db.base import SessionLocal +from app.db.models import Group, GroupMember, User, Workflow +from app.db.models_apps import App, AppGrant, AppVersion + +USER = "user" +GROUP = "group" +EVERYONE = "everyone" + + +def _name(prefix: str) -> str: + """用例自己的名字:别的工作流、应用、账号同名会串进这次断言(测试会话共用一个库)。""" + return f"{prefix}-{uuid.uuid4().hex[:8]}" + + +async def _workflow(version: int = 1) -> str: + """一份已发布的工作流;只为了 pins 里有一个真实的工作流 id,判定本身不读它。""" + async with SessionLocal() as session: + wf = Workflow(name=_name("周销售"), graph={}, status="published", published_version=version) + session.add(wf) + await session.commit() + return wf.id + + +async def _app(*pins, name: str = "看板", status: str = "active", draft_pins: list | None = None) -> str: + """一个应用:当前发布版(v1)固定 pins;给了 draft_pins 就再存一版没发布的草稿(v2)。""" + async with SessionLocal() as session: + app = App(name=_name(name), status=status, published_version=1) + session.add(app) + await session.flush() + session.add(AppVersion(app_id=app.id, version=1, spec={}, spec_hash="x", pins=list(pins))) + if draft_pins is not None: + session.add(AppVersion(app_id=app.id, version=2, spec={}, spec_hash="y", pins=list(draft_pins))) + await session.commit() + return app.id + + +async def _grant(app_id: str, kind: str, principal: str, role: str) -> None: + async with SessionLocal() as session: + session.add(AppGrant(app_id=app_id, principal_kind=kind, principal=principal, role=role)) + await session.commit() + + +async def _person(username: str, *, role: str = "user", disabled: bool = False, groups: tuple[str, ...] = ()) -> str: + """建一个人(要判组、停用、角色时);返回用户名。""" + async with SessionLocal() as session: + user = User(username=username, display_name=username, role=role, disabled=disabled) + session.add(user) + await session.flush() + for group in groups: + row = Group(name=group, label=group) + session.add(row) + await session.flush() + session.add(GroupMember(group_id=row.id, user_id=user.id)) + await session.commit() + return username + + +def _principal(username: str, *, role: str = "user", mode: str = "local") -> Principal: + return Principal(username=username, role=role, verified=True, mode=mode) + + +# -------------------------------------------------------------------------- +# 给本人、给组、给所有人 +# -------------------------------------------------------------------------- + +async def test_a_grant_to_the_person_lets_them_use_the_pinned_version(): + wf = await _workflow() + app = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + carol = _name("carol") + await _grant(app, USER, carol, "use") + + async with SessionLocal() as session: + assert (await usable_calibers(session, carol)).get((wf, 1)) == "use" + assert await caliber_role(session, carol, wf, 1) == "use" + assert await caliber_granting_app(session, carol, wf, 1) == app + # 当面请求给的是 Principal 时同一份判定 + assert await caliber_role(session, _principal(carol), wf, 1) == "use" + + +async def test_a_grant_to_a_group_reaches_the_people_in_it(): + wf = await _workflow() + app = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + fin = _name("财务") + dave, erin = _name("dave"), _name("erin") + await _person(dave, groups=(fin,)) + await _person(erin) + await _grant(app, GROUP, fin, "observe") + + async with SessionLocal() as session: + # 给用户名:组从名录取;给 Principal:他带的组是空的,也从名录取 + assert await caliber_role(session, dave, wf, 1) == "observe" + assert await caliber_role(session, _principal(dave), wf, 1) == "observe" + # 不在这个组里的人拿不到 + assert await caliber_role(session, erin, wf, 1) is None + assert (wf, 1) not in await usable_calibers(session, erin) + + +async def test_a_grant_to_everyone_reaches_anyone_with_an_identity(): + wf = await _workflow() + app = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + await _grant(app, EVERYONE, "", "use") + + async with SessionLocal() as session: + assert await caliber_role(session, _name("zoe"), wf, 1) == "use" + assert await caliber_role(session, _principal(_name("amy")), wf, 1) == "use" + assert (await usable_calibers(session, _name("leo"))).get((wf, 1)) == "use" + + +# -------------------------------------------------------------------------- +# 固定在哪一版:版本要精确对上,归档、草稿不算 +# -------------------------------------------------------------------------- + +async def test_only_the_exact_workflow_and_version_is_granted(): + wf = await _workflow(version=2) + other = await _workflow() + app = await _app({"alias": "new", "workflow_id": wf, "version": 2}, + {"alias": "old", "workflow_id": other, "version": 1}) + carol = _name("carol") + await _grant(app, USER, carol, "use") + + async with SessionLocal() as session: + found = await usable_calibers(session, carol) + assert found.get((wf, 2)) == "use" and found.get((other, 1)) == "use" + # 同一个工作流的别的版本没有固定,不算能用 + assert await caliber_role(session, carol, wf, 1) is None + assert (wf, 1) not in found + # 别的工作流的同一版也不算 + assert await caliber_role(session, carol, _name("别的口径"), 2) is None + + +async def test_an_archived_app_grants_nothing(): + wf = await _workflow() + app = await _app({"alias": "week", "workflow_id": wf, "version": 1}, status="archived") + carol = _name("carol") + await _grant(app, USER, carol, "use") + + async with SessionLocal() as session: + assert await caliber_role(session, carol, wf, 1) is None + assert (wf, 1) not in await usable_calibers(session, carol) + + +async def test_a_caliber_pinned_only_by_a_draft_is_not_granted(): + wf = await _workflow() + # 当前发布版(v1)没固定它,v2 的草稿里才有 + app = await _app({"alias": "other", "workflow_id": await _workflow(), "version": 1}, + draft_pins=[{"alias": "week", "workflow_id": wf, "version": 1}]) + carol = _name("carol") + await _grant(app, USER, carol, "use") + + async with SessionLocal() as session: + assert await caliber_role(session, carol, wf, 1) is None + assert (wf, 1) not in await usable_calibers(session, carol) + + +# -------------------------------------------------------------------------- +# 档位:use / observe / manage 取最高 +# -------------------------------------------------------------------------- + +async def test_the_highest_grant_wins_and_names_the_app_it_came_from(): + wf = await _workflow() + only_use = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + observing = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + managing = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + elsewhere = await _app({"alias": "other", "workflow_id": await _workflow(), "version": 1}) + carol = _name("carol") + await _grant(only_use, USER, carol, "use") + await _grant(observing, USER, carol, "observe") + await _grant(managing, USER, carol, "manage") + await _grant(elsewhere, USER, carol, "use") + + async with SessionLocal() as session: + assert (await usable_calibers(session, carol)).get((wf, 1)) == "manage" + assert await caliber_role(session, carol, wf, 1) == "manage" + assert await caliber_granting_app(session, carol, wf, 1) == managing + + +async def test_a_grant_below_use_is_not_a_grant(): + wf = await _workflow() + app = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + carol = _name("carol") + await _grant(app, USER, carol, "reader") + + async with SessionLocal() as session: + assert await caliber_role(session, carol, wf, 1) is None + assert (wf, 1) not in await usable_calibers(session, carol) + + +async def test_a_grant_on_an_app_that_does_not_pin_this_version_grants_nothing(): + wf = await _workflow() + app = await _app({"alias": "week", "workflow_id": wf, "version": 7}) + carol = _name("carol") + await _grant(app, USER, carol, "manage") + + async with SessionLocal() as session: + assert await caliber_role(session, carol, wf, 1) is None + assert await caliber_granting_app(session, carol, wf, 1) is None + assert (wf, 1) not in await usable_calibers(session, carol) + + +# -------------------------------------------------------------------------- +# 没有主体、停用、没有授权 +# -------------------------------------------------------------------------- + +async def test_without_a_subject_there_is_no_caliber_authorization(): + wf = await _workflow() + app = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + await _grant(app, EVERYONE, "", "manage") # 所有人都有,但没有主体的人不算 + + async with SessionLocal() as session: + assert await caliber_role(session, None, wf, 1) is None + assert await caliber_role(session, "", wf, 1) is None + assert await caliber_role(session, " ", wf, 1) is None + # 关登录的署名可以是空的;管理员、关登录都不在这里自动放行 + assert await caliber_role(session, Principal(username=None, role="admin", mode="off", via="off"), wf, 1) is None + assert await usable_calibers(session, None) == {} + + +async def test_a_disabled_person_has_no_caliber_authorization(): + wf = await _workflow() + app = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + frank = await _person(_name("frank"), disabled=True) + await _grant(app, USER, frank, "manage") + + async with SessionLocal() as session: + assert await caliber_role(session, frank, wf, 1) is None + assert await caliber_role(session, _principal(frank), wf, 1) is None + assert (wf, 1) not in await usable_calibers(session, frank) + + +async def test_a_person_without_a_grant_gets_nothing(): + wf = await _workflow() + app = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + gina = _name("gina") + await _grant(app, USER, _name("someone-else"), "manage") + + async with SessionLocal() as session: + assert await caliber_role(session, gina, wf, 1) is None + assert await caliber_granting_app(session, gina, wf, 1) is None + assert (wf, 1) not in await usable_calibers(session, gina) + + +# -------------------------------------------------------------------------- +# 角色不是资产授权 +# -------------------------------------------------------------------------- + +async def test_builder_and_admin_roles_are_not_asset_authorization(): + wf = await _workflow() + app = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + bob = await _person(_name("bob"), role="builder") + root = await _person(_name("root"), role="admin") + + async with SessionLocal() as session: + # 搭建者、管理员,没有授权就是没有:这两个函数不按角色放行(调用方显式放行搭建者及以上) + assert await caliber_role(session, bob, wf, 1) is None + assert await caliber_role(session, _principal(bob, role="builder"), wf, 1) is None + assert await caliber_role(session, root, wf, 1) is None + assert await caliber_role(session, _principal(root, role="admin"), wf, 1) is None + # 关登录的 Principal 也一样:拿到的是授权那一档,不是 manage + assert await caliber_role(session, _principal(_name("carol"), mode="off"), wf, 1) is None + + # 有了授权,拿到的也是授权那一档本身(搭建者不因此升成 manage) + await _grant(app, USER, bob, "observe") + carol = _name("carol") + await _grant(app, USER, carol, "use") + async with SessionLocal() as session: + assert await caliber_role(session, _principal(bob, role="builder"), wf, 1) == "observe" + assert await caliber_role(session, _principal(carol, mode="off"), wf, 1) == "use" + + +# -------------------------------------------------------------------------- +# 正式出具复用同一份判定(ledger/issue._granting_app) +# -------------------------------------------------------------------------- + +async def test_issue_granting_app_uses_the_same_judgment(): + from app.ledger import issue as ledger_issue + + wf = await _workflow() + app = await _app({"alias": "week", "workflow_id": wf, "version": 1}) + carol = _name("carol") + await _grant(app, USER, carol, "observe") + + async with SessionLocal() as session: + # 至少 use 的授权够出具,靠的是这份应用 + assert await ledger_issue._granting_app(session, _principal(carol), wf, 1) == app + # 没有授权的使用者、搭建者都没有「靠哪份应用」:拒绝的话是 check_target 里那句「请搭建者出具」 + assert await ledger_issue._granting_app(session, _principal(_name("dave")), wf, 1) is None + assert await ledger_issue._granting_app(session, _principal(_name("bob"), role="builder"), wf, 1) is None + # 换一版不在授权里 + assert await ledger_issue._granting_app(session, _principal(carol), wf, 2) is None + + archived = await _app({"alias": "week", "workflow_id": wf, "version": 1}, status="archived") + await _grant(archived, USER, carol, "manage") + async with SessionLocal() as session: + # 归档的应用固定不住任何东西:还是原来那份发布着的 + assert await ledger_issue._granting_app(session, _principal(carol), wf, 1) == app diff --git a/backend/tests/test_caliber_bindings.py b/backend/tests/test_caliber_bindings.py new file mode 100644 index 00000000..c54ef2e2 --- /dev/null +++ b/backend/tests/test_caliber_bindings.py @@ -0,0 +1,754 @@ +"""K04 试点业务映射与编辑能力:显式声明的版本化受控模板绑定,定义和取数 SQL 一次改到位。 + +- 合成 A/B/C/D 四单(tests/binding_samples.py,任务书 6.2):旧定义(下单时间、不过滤退款)十月 3 单 900 元; + 经**真实 PATCH operations** 把两个共享 SQL 的指标一起改成支付时间 + 排除全额退款之后,真实试跑的独立预期 2 单 500 元 + (A 纳入、B 跨期排除、C 排除、D 保留); +- 一次变更把定义和 SQL 放在同一个事务里改:版本只 +1,args.sql 真的变了(剩下那一段新写法),binding 的 values / + rendered_hash / fingerprint 跟着走,没提到的键、别的节点和扩展字段一个字不动; +- 换查询窗口只改参数,不建定义版本; +- 同步不了的一律**定义照常保存、SQL 一个字不动**,照实说 needs_update / unsupported + 原因 + 影响对象 + 该做什么, + 并且在**发运行之前**拦住试跑(旧 SQL 的数不能冒充新定义):复杂 SQL(没有 [[time_role]] 的落点)、SQL 被手工改过 + (哈希对不上)、同一条 SQL 上的两个指标说法打架、画布上手工改了定义; +- 读接口给服务端能力描述:能改哪些业务字段、允许值、现在的值、同步状态;aligned 不等于验证通过 + (semantic_unverified 和质量状态不因它变 pass); +- 非法值、幂等重放、并发同键、没有业务字段的旧资产照旧。 + +真引擎跑试跑(run_manager.setup + fixtures 里的真实 SQLite 订单库),不发模型请求。 +""" +from __future__ import annotations + +import asyncio +import copy + +import pytest +from sqlalchemy import delete, func, select + +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, DataSource, Run, Workflow, WorkflowVersion +from app.engine.runner import run_manager +from app.ledger import bindings +from tests import binding_samples as S +from tests.test_ledger_docdraft_api import client # noqa: F401 - fixture 和起草用例共用 + +#: 这个文件自己建的工作流(连同版本、草稿)和临时数据源跑完删掉 +OWN_PREFIX = "K04 " + + +@pytest.fixture(autouse=True) +async def cleanup_own_rows(): + yield + async with SessionLocal() as session: + workflow_ids = list((await session.execute( + select(Workflow.id).where(Workflow.name.like(f"{OWN_PREFIX}%")))).scalars()) + if workflow_ids: + for model in (WorkflowVersion, CaliberDraft): + await session.execute(delete(model).where(model.workflow_id.in_(workflow_ids))) + await session.execute(delete(Workflow).where(Workflow.id.in_(workflow_ids))) + for name in S.MADE["sources"]: + await session.execute(delete(DataSource).where(DataSource.name == name)) + S.MADE["sources"].clear() + await session.commit() + + +@pytest.fixture(autouse=True) +async def use_iteration_free_source(tmp_path): + """每个用例一个真实的 SQLite 订单库:图里的查询工具指向它,试跑真的查它。""" + await S.fresh_source(tmp_path / "orders.db") + yield + + +@pytest.fixture(autouse=True) +async def engine_up(): + """试跑走真引擎(探针图里没有报告节点,不发模型请求)。""" + await run_manager.setup() + yield + await run_manager.shutdown() + + +def patch_url(draft_id: str) -> str: + return f"/api/ledger/drafts/{draft_id}" + + +def biz_ops(*, metrics=("m1", "m2"), time_role="payment_time", refund_rule="exclude_full_refund") -> list[dict]: + """把这几条指标的时间口径和退款规则一起改掉的字段操作。""" + out: list[dict] = [] + for metric_id in metrics: + if time_role is not None: + out.append({"op": "set", "metric_id": metric_id, "path": "/time_role", "value": time_role}) + if refund_rule is not None: + out.append({"op": "set", "metric_id": metric_id, "path": "/refund_rule", "value": refund_rule}) + return out + + +async def patch_biz(client, body: dict, operations: list[dict], **extra): + payload = {"operations": operations, "expected_revision": body["revision"], **extra} + return await client.patch(patch_url(body["id"]), json=payload) + + +async def trial(client, body: dict, values: dict | None = None) -> dict: + """按入口字段真跑一次试跑(真实引擎)。""" + res = await client.post(f"/api/ledger/drafts/{body['id']}/trial", json={"inputs": dict(values or S.OCTOBER)}) + assert res.status_code == 200, res.text + return res.json() + + +def values_of(trial_body: dict) -> dict[str, float]: + return {metric["id"]: float(metric["value"]) for metric in trial_body["metrics"] if metric.get("value") is not None} + + +async def graph_of(workflow_id: str, version: int | None = None) -> dict: + async with SessionLocal() as session: + workflow = await session.get(Workflow, workflow_id) + if version is None or version == workflow.version: + return copy.deepcopy(workflow.graph) + row = (await session.execute(select(WorkflowVersion).where( + WorkflowVersion.workflow_id == workflow_id, WorkflowVersion.version == version))).scalars().one() + return copy.deepcopy(row.graph) + + +async def versions_of(workflow_id: str) -> list[int]: + async with SessionLocal() as session: + return list((await session.execute(select(WorkflowVersion.version).where( + WorkflowVersion.workflow_id == workflow_id).order_by(WorkflowVersion.version))).scalars()) + + +async def runs_of(workflow_id: str) -> int: + async with SessionLocal() as session: + return int(await session.scalar(select(func.count(Run.id)).where(Run.workflow_id == workflow_id)) or 0) + + +def fetch_config(graph: dict, node_id: str = "fetch") -> dict: + node = next(n for n in graph["nodes"] if n["id"] == node_id) + return node["data"]["config"] + + +def card_metric(graph: dict, metric_id: str, node_id: str = "card") -> dict: + config = next(n for n in graph["nodes"] if n["id"] == node_id)["data"]["config"] + return next(metric for metric in config["metrics"] if metric["id"] == metric_id) + + +# ========================================================================== +# 正向:旧定义 3,一次变更之后 2 +# ========================================================================== + +async def test_the_old_definition_counts_three_orders_in_october(client): + """旧定义(按下单时间、不排除退款):十月房子的独立预期是 3 单——真引擎试跑对得上。""" + body = await S.draft(S.graph()) + done = await trial(client, body) + assert done["status"] == "succeeded", done.get("error") + assert values_of(done) == {"m1": S.EXPECTED["old"]["orders"], "m2": S.EXPECTED["old"]["amount"]} + assert done["version"] == 1 + + +async def test_one_patch_moves_two_shared_sql_metrics_and_the_sql_with_them(client): + """E05 的正向样例:一次字段变更把两个共享 SQL 的指标改成支付时间 + 排除全额退款,SQL 一起改,版本只 +1。""" + body = await S.draft(S.graph()) + before = await graph_of(body["workflow_id"]) + before_sql = fetch_config(before)["args"]["sql"] + before_binding = fetch_config(before)[bindings.KEY] + + res = await patch_biz(client, body, [*biz_ops(), + {"op": "set", "metric_id": "m1", "path": "/definition/text", + "value": "订单数按支付时间统计,全额退款排除"}]) + assert res.status_code == 200, res.text + made = res.json() + assert made["version"] == 2 and await versions_of(body["workflow_id"]) == [1, 2] + + change = made["change"] + assert change["applied"] is True and change["binding"]["synced"] is True + assert change["metrics"] == ["m1", "m2"] + assert change["binding"]["status"] == bindings.ALIGNED and change["binding"]["checked"] is True + assert change["binding"]["synced"] is True and change["binding"]["fix"] == "none" + assert "不等于业务验证通过" in change["binding"]["reason"] + assert set(change["binding"]["binding_fingerprints"]) == {"fetch"} + + after = await graph_of(body["workflow_id"]) + sql = fetch_config(after)["args"]["sql"] + assert sql == S.render(S.NEW) and sql != before_sql + assert "o.paid_at" in sql and "o.refund_state <> 'full'" in sql and "o.ordered_at" not in sql + # 没提到的:这条取数节点上别的键、别的节点、图里的扩展字段一个字不动 + assert fetch_config(after)["hints"] == {"keep": "me"} + assert fetch_config(after)["tool"] == fetch_config(before)["tool"] + assert [n["id"] for n in after["nodes"]] == [n["id"] for n in before["nodes"]] + assert next(n for n in after["nodes"] if n["id"] == "start") == next(n for n in before["nodes"] if n["id"] == "start") + updated = fetch_config(after)[bindings.KEY] + assert updated["values"] == S.NEW and updated["rendered_hash"] == bindings.sql_hash(sql) + assert updated["fingerprint"] == change["binding"]["binding_fingerprints"]["fetch"] + assert updated["fingerprint"] != bindings.fingerprint(before_binding) + assert updated["domain"] == "order_sales" and updated["mapping_version"] == 1 + # 定义也改了,两个指标一致 + assert card_metric(after, "m1")["time_role"] == "payment_time" + assert card_metric(after, "m2")["refund_rule"] == "exclude_full_refund" + assert card_metric(after, "m1")["definition"]["text"] == "订单数按支付时间统计,全额退款排除" + + # 真跑一次:独立预期 2 单 500 元 + done = await trial(client, body) + assert done["status"] == "succeeded", done.get("error") + assert values_of(done) == {"m1": S.EXPECTED["new"]["orders"], "m2": S.EXPECTED["new"]["amount"]} + assert done["version"] == 2 + + # 换查询窗口只是请求变化:不建定义版本(九月没有订单:计数是 0,金额是空值) + september = await trial(client, body, S.SEPTEMBER) + assert september["status"] == "succeeded", september.get("error") + assert values_of(september) == {"m1": 0.0} + assert next(m for m in september["metrics"] if m["id"] == "m2").get("value") is None + assert await versions_of(body["workflow_id"]) == [1, 2] + + +async def test_the_query_snapshot_records_which_binding_produced_the_sql(client): + """查询快照记下这条 SQL 是哪份绑定的哪一次展开(业务值 + 绑定指纹):事后认得出「这个数是按支付时间算的」。""" + from app.core.artifact_store import load + from app.engine.evidence_reader import read_sealed + + body = await S.draft(S.graph()) + await patch_biz(client, body, biz_ops()) + done = await trial(client, body) + assert done["status"] == "succeeded", done.get("error") + + sealed = await read_sealed(done["run_id"]) + artifact = next(iter(sealed.queries)) + snapshot = load(artifact) + material = snapshot["binding"] + assert material["domain"] == "order_sales" and material["mapping_version"] == 1 + assert material["values"] == S.NEW and material["binder"] == bindings.BINDER + assert material["fingerprint"] == (await graph_of(body["workflow_id"]))["nodes"][1]["data"]["config"][ + bindings.KEY]["fingerprint"] + # 快照里记的实际语句是渲染过参数的那一条(K01),绑定材料说的是它来自哪次展开(模板展开的那一条, + # {{ input.* }} 还在里面)——两种哈希各记各的,不混 + assert "o.paid_at >=" in snapshot["sql"] and "'2026-10-01'" in snapshot["sql"] + configured = fetch_config(await graph_of(body["workflow_id"]))["args"]["sql"] + assert material["rendered_hash"] == bindings.sql_hash(configured) + assert "template" not in material and "snippets" not in material + + +# ========================================================================== +# 反例:同步不了的定义照常保存,SQL 一个字不动,运行之前拦住 +# ========================================================================== + +async def test_a_complex_sql_is_kept_as_a_draft_with_a_specific_unsupported(client): + """复杂 SQL 反例:时间条件写死在 CTE 里,受控模板没有 [[time_role]] 的落点——定义照常保存,SQL 不动,不许跑。""" + body = await S.draft(S.complex_graph()) + before = await graph_of(body["workflow_id"]) + runs_before = await runs_of(body["workflow_id"]) + + res = await patch_biz(client, body, biz_ops(metrics=("m1", "m2"))) + assert res.status_code == 200, res.text + made = res.json() + assert made["version"] == 2 + change = made["change"] + assert change["binding"]["synced"] is False and change["binding"]["status"] == bindings.UNSUPPORTED + assert change["binding"]["fix"] == "author" + assert "没有「统计时间口径」的落点" in change["binding"]["unsupported_reason"] + assert change["binding"]["metrics"] == ["m1", "m2"] and change["binding"]["nodes"][0]["node_id"] == "fetch" + + after = await graph_of(body["workflow_id"]) + assert fetch_config(after)["args"]["sql"] == fetch_config(before)["args"]["sql"] + assert fetch_config(after)[bindings.KEY]["values"] == {"refund_rule": "include_all"} # 绑定也没被改 + assert card_metric(after, "m1")["time_role"] == "payment_time" # 定义存下来了,草稿还在 + + # 发运行之前拦住:一条 SQL 都不发,也不把旧数当新定义交回 + refused = await client.post(patch_url(body["id"]) + "/trial", json={"inputs": dict(S.OCTOBER)}) + assert refused.status_code == 200, refused.text + assert refused.json()["status"] == "failed" and refused.json()["error"] + assert refused.json()["metrics"] == [] + assert await runs_of(body["workflow_id"]) == runs_before + shown = (await client.get(patch_url(body["id"]))).json() + assert shown["binding"]["status"] == bindings.UNSUPPORTED + assert shown["trial"]["status"] in ("failed", "stale") or shown["trial"]["status"] == "needs_input" + + +async def test_a_hand_edited_sql_is_needs_update_and_is_never_rewritten(client): + """SQL 被手工改过(和绑定记录对不上):不覆盖人的修改,照实说 needs_update,也不许跑。""" + graph = S.graph() + fetch_config(graph)["args"]["sql"] = S.render(S.OLD) + " -- 手工加的注释" + body = await S.draft(graph) + runs_before = await runs_of(body["workflow_id"]) + + res = await patch_biz(client, body, biz_ops()) + assert res.status_code == 200, res.text + change = res.json()["change"] + assert change["binding"]["synced"] is False and change["binding"]["status"] == bindings.NEEDS_UPDATE + assert change["binding"]["fix"] == "manual" + assert "不是这份绑定展开出来的" in change["binding"]["reason"] + after = await graph_of(body["workflow_id"]) + assert fetch_config(after)["args"]["sql"].endswith("-- 手工加的注释") + assert fetch_config(after)[bindings.KEY]["values"] == S.OLD # 绑定也没被改 + + refused = await client.post(patch_url(body["id"]) + "/trial", json={"inputs": dict(S.OCTOBER)}) + assert refused.json()["status"] == "failed" + assert await runs_of(body["workflow_id"]) == runs_before + + +async def test_two_metrics_disagreeing_on_one_sql_are_a_conflict(client): + """同一条 SQL 上的两个指标说法不一致:一个节点只有一份 SQL,先统一再改——SQL 不动,也不许跑。""" + body = await S.draft(S.graph()) + before = await graph_of(body["workflow_id"]) + res = await patch_biz(client, body, [{"op": "set", "metric_id": "m1", "path": "/time_role", + "value": "payment_time"}]) + assert res.status_code == 200, res.text + change = res.json()["change"] + assert change["binding"]["synced"] is False and change["binding"]["status"] == bindings.NEEDS_UPDATE + assert change["binding"]["fix"] == "manual" and "说法不一致" in change["binding"]["reason"] + assert fetch_config(await graph_of(body["workflow_id"]))["args"]["sql"] == fetch_config(before)["args"]["sql"] + + runs_before = await runs_of(body["workflow_id"]) + refused = await client.post(patch_url(body["id"]) + "/trial", json={"inputs": dict(S.OCTOBER)}) + assert refused.json()["status"] == "failed" + assert await runs_of(body["workflow_id"]) == runs_before + + +async def test_a_definition_edited_on_the_canvas_reads_as_needs_update(client): + """画布上手工改定义(绕过字段变更服务):读接口如实说 needs_update,试跑在发运行之前拦住。""" + body = await S.draft(S.graph()) + graph = await graph_of(body["workflow_id"]) + # 两个指标在画布上一起改成支付时间(说法仍然一致):定义走到了实现前面,SQL 还是旧的那条 + card_metric(graph, "m1")["time_role"] = "payment_time" + card_metric(graph, "m2")["time_role"] = "payment_time" + saved = await client.patch(f"/api/workflows/{body['workflow_id']}", + json={"graph": graph, "expected_revision": body["revision"]}) + assert saved.status_code == 200 and saved.json()["version"] == 2, saved.text + + shown = (await client.get(patch_url(body["id"]))).json() + assert shown["binding"]["status"] == bindings.NEEDS_UPDATE + assert shown["binding"]["fix"] == "sync" and "可以按受控模板" in shown["binding"]["reason"] + assert shown["binding"]["metric_values"]["m1"]["time_role"] == "payment_time" + + runs_before = await runs_of(body["workflow_id"]) + refused = await client.post(patch_url(body["id"]) + "/trial", json={"inputs": dict(S.OCTOBER)}) + assert refused.json()["status"] == "failed" and refused.json()["metrics"] == [] + assert "绑定里还是旧的" in refused.json()["error"] + assert await runs_of(body["workflow_id"]) == runs_before + + +async def test_an_unaligned_caliber_cannot_be_composed_or_recalled(client): + """派生那条路(组合式问数、召回、对账、评测)问的是同一份 load_pinned:对不上就派生不出来。""" + from app.ledger import derive + + body = await S.draft(S.graph()) + # 只改一个指标 → 同一条 SQL 上的两个指标说法不一致:派生不出来 + await patch_biz(client, body, [{"op": "set", "metric_id": "m1", "path": "/time_role", + "value": "payment_time"}]) + async with SessionLocal() as session: + with pytest.raises(derive.NotDerivable) as refused: + await derive.load_pinned(session, body["workflow_id"], 2, "card") + assert refused.value.code == derive.BINDING_UNALIGNED + assert "说法不一致" in refused.value.message + + +async def test_the_raw_graph_run_stops_before_computing_any_metric(client): + """原图直接运行(不走派生):口径卡在算数之前就停——旧 SQL 的结果不许冒充新定义。""" + from tests.ledger_samples import wait as wait_run + + body = await S.draft(S.graph()) + await patch_biz(client, body, [{"op": "set", "metric_id": "m1", "path": "/time_role", + "value": "payment_time"}]) + graph = await graph_of(body["workflow_id"]) + run = await run_manager.start(graph=graph, input_payload=dict(S.OCTOBER), run_class="exploratory", + origin_kind="chat", origin={"conversation_id": "k04-raw"}) + row = await wait_run(run.id) + assert row.status == "failed" and "对不上" in str(row.error) + assert "没有计算任何指标" in str(row.error) + + +# ========================================================================== +# 非法值、幂等、并发 +# ========================================================================== + +@pytest.mark.parametrize("path,value", [("/time_role", "yesterday"), ("/refund_rule", "full_only"), + ("/time_role", ""), ("/refund_rule", 3)]) +async def test_an_illegal_business_value_is_refused(client, path, value): + body = await S.draft(S.graph()) + res = await patch_biz(client, body, [{"op": "set", "metric_id": "m1", "path": path, "value": value}]) + assert res.status_code == 422, res.text + assert res.json()["code"] in ("operation_value",) and res.json()["detail"] + assert await versions_of(body["workflow_id"]) == [1] + + +async def test_the_business_change_replays_idempotently_and_refuses_concurrently(client): + """同一个 request_id 重放不新增版本;同键并发只落一版。""" + body = await S.draft(S.graph()) + operations = biz_ops() + first = await patch_biz(client, body, operations, request_id="k04-0001") + assert first.status_code == 200 and first.json()["version"] == 2, first.text + again = await patch_biz(client, body, operations, request_id="k04-0001") + assert again.status_code == 200 and again.json().get("replayed") is True + assert await versions_of(body["workflow_id"]) == [1, 2] + + other = await S.draft(S.graph()) + payload = {"operations": biz_ops(), "expected_revision": other["revision"], "request_id": "k04-race"} + url = patch_url(other["id"]) + raced = await asyncio.gather(client.patch(url, json=payload), client.patch(url, json=payload)) + assert sorted(res.status_code for res in raced) == [200, 200], (raced[0].text, raced[1].text) + assert await versions_of(other["workflow_id"]) == [1, 2] + + +# ========================================================================== +# 转抄卡(caliber_from):原图直接跑时,本地那句 SQL 也必须和钉住的定义对得上 +# ========================================================================== + +def test_analyzing_a_chained_card_uses_the_pinned_definitions_and_the_local_nodes(): + """转抄卡在本图里没有自己的指标:拿**钉住那一版**的定义(式子已按源→本地映射改写到本地节点)判本地取数节点。""" + upstream = asyncio.run(S.upstream()) if False else None # 纯函数用例,不需要库 + rename = {"fetch": "c1_fetch"} + graph = S.chained_graph({"workflow_id": "up", "card": "card"}, version=2, local_values=S.OLD, rename=rename) + pinned_metrics = [ + {"id": "m1", "name": "订单数", "expression": "cell(nodes.c1_fetch, 0, 'orders')", + "time_role": "payment_time", "refund_rule": "exclude_full_refund"}, + {"id": "m2", "name": "销售额", "expression": "cell(nodes.c1_fetch, 0, 'amount')", + "time_role": "payment_time"}, + ] + report = bindings.analyze(graph, "card", pinned_metrics) + assert upstream is None + # 判的是本地那个取数节点(映射之后的名字),而不是「没声明业务字段」而放行 + assert report.status == bindings.NEEDS_UPDATE and report.blocked + assert [node.node_id for node in report.nodes] == ["c1_fetch"] + assert report.nodes[0].declared == {"time_role": "payment_time", "refund_rule": "exclude_full_refund"} + assert report.nodes[0].values == S.OLD and report.metrics == ("m1", "m2") + assert bindings.blocking(report) + + # 本地节点就是那一版的展开:aligned,放行 + aligned = S.chained_graph({"workflow_id": "up", "card": "card"}, version=2, local_values=S.NEW, rename=rename) + assert bindings.analyze(aligned, "card", pinned_metrics).status == bindings.ALIGNED + + +async def test_a_chained_card_never_shows_the_old_local_numbers_as_the_pinned_definition(client): + """复核里的反例:上游 v2 是「按支付时间」(2 单 500),消费侧本地那句取数还停在旧的「按下单时间」(3 单 900)。 + + 原图直接跑必须在算数之前拦住——不能把 3 单 900 元当成 v2 的定义交出来。 + """ + from app.engine.evidence_reader import metric_cards, read_sealed + from tests.ledger_samples import wait as wait_run + + upstream = await S.upstream() + graph = S.chained_graph(upstream, version=2, local_values=S.OLD) + # 先证明本地那句 SQL 自己跑出来确实是旧定义的数(3 单 900 元):它不是错的,错的是拿它当新定义 + assert S.graph(values=S.OLD)["nodes"][1]["data"]["config"]["args"]["sql"] == S.render(S.OLD) + + run = await run_manager.start(graph=graph, input_payload=dict(S.OCTOBER), run_class="exploratory", + origin_kind="chat", origin={"conversation_id": "k04-chain"}) + row = await wait_run(run.id) + assert row.status == "failed", row.error + assert "对不上" in str(row.error) and "没有计算任何指标" in str(row.error) + assert "绑定里还是旧的" in str(row.error) + sealed = await read_sealed(run.id) + assert list(metric_cards(sealed)) == [] # 一个数都没算出来,更没有 3 单 900 元 + + +async def test_a_chained_card_with_the_pinned_sql_runs_and_gives_the_pinned_numbers(client): + """同一张转抄卡,本地取数就是钉住那一版的展开(还带源→本地的节点改名映射):照常跑,数就是新定义的 2 单 500 元。""" + from app.engine.evidence_reader import metric_cards, read_sealed + from tests.ledger_samples import wait as wait_run + + upstream = await S.upstream() + graph = S.chained_graph(upstream, version=2, local_values=S.NEW, rename={"fetch": "c1_fetch"}) + run = await run_manager.start(graph=graph, input_payload=dict(S.OCTOBER), run_class="exploratory", + origin_kind="chat", origin={"conversation_id": "k04-chain-ok"}) + row = await wait_run(run.id) + assert row.status == "succeeded", row.error + sealed = await read_sealed(run.id) + computed = {metric["id"]: float(metric["value"]) for _node, _artifact, card in metric_cards(sealed) + for metric in card.get("metrics") or []} + assert computed == {"m1": S.EXPECTED["new"]["orders"], "m2": S.EXPECTED["new"]["amount"]} # 2 单 500 元 + + +async def test_a_composed_copy_of_an_aligned_caliber_is_not_blocked(client): + """组合式问数把口径拷进另一张图时参数只渲染一次(K01 契约):这份副本不该被判成「SQL 和绑定对不上」。 + + 拷出来的节点 args 已经是渲染好的字面语句,和「模板展开」不可能逐字相等——业务语义在派生那一刻按源版本核过 + (load_pinned),这里只比这一版的指标定义和副本上记的业务值。改过 args 的副本契约作废,照普通节点判。 + """ + from app.engine.nodes.metrics import rename_definition + from app.ledger import derive + + workflow_id = await S.publish(S.graph(values=S.NEW), name=f"{OWN_PREFIX}组合") + async with SessionLocal() as session: + pinned = await derive.load_pinned(session, workflow_id, 1, "card") + block = derive.caliber_block(pinned, prefix="c1_", inputs={"start": "2026-10-01", "end": "2026-11-01"}) + graph = derive.assemble("caliber_probe", [block], fields=pinned.entry_fields, defaults=pinned.defaults).graph + definitions = [rename_definition(metric, {"fetch": "c1_fetch"}) for metric in pinned.metrics] + + report = bindings.analyze(graph, "c1_card", definitions) + assert report.status == bindings.ALIGNED and not report.blocked + assert [node.node_id for node in report.nodes] == ["c1_fetch"] + assert report.nodes[0].values == S.NEW + + # 副本的 args 被手工改过(契约作废):不再是渲染副本,按普通节点判——SQL 和绑定对不上,拦住 + broken = copy.deepcopy(graph) + fetch = next(node for node in broken["nodes"] if node["id"] == "c1_fetch") + fetch["data"]["config"]["args"]["sql"] = "SELECT COUNT(*) AS orders, SUM(amount) AS amount FROM orders" + assert bindings.analyze(broken, "c1_card", definitions).status == bindings.NEEDS_UPDATE + + +# ========================================================================== +# 绑定自己就不自洽:模板里的 token 没有值 +# ========================================================================== + +#: 引号里写 token 的受控模板(复核要求覆盖裸 token 和引号内的 token 两种写法) +QUOTED_TEMPLATE = ("SELECT COUNT(*) AS orders, SUM(o.amount) AS amount FROM orders o " + "WHERE o.pay_state = '[[refund_rule]]' AND ([[time_role]])") +QUOTED_SNIPPETS = {"refund_rule": {"include_all": "any", "exclude_full_refund": "paid_only"}, + "time_role": S.SNIPPETS["time_role"]} +QUOTED_VALUES = {"refund_rule": "exclude_full_refund", "time_role": "payment_time"} + + +@pytest.mark.parametrize("template,snippets,full_values,broken_values,label", [ + # 裸 token:模板里 [[time_role]] 有映射,当前业务值里却没有它 + (S.TEMPLATE, S.SNIPPETS, S.NEW, {"refund_rule": "exclude_full_refund"}, "统计时间口径"), + # 引号里的 token:'[[refund_rule]]' 同样不能没值就放行 + (QUOTED_TEMPLATE, QUOTED_SNIPPETS, QUOTED_VALUES, {"time_role": "payment_time"}, "退款处理"), +]) +def test_a_token_without_a_value_is_unsupported_and_is_never_written_back(template, snippets, full_values, + broken_values, label): + """模板/允许映射里有 token、当前业务值却缺这个字段:判 unsupported(点名是哪个字段),不写 SQL、不记材料。""" + sql = bindings.render(template, snippets, full_values) # 先在完整取值下展开(对照组:展开得了) + assert "[[" not in sql + graph = S.graph(values=S.NEW, metrics=S.card_metrics()) + config = fetch_config(graph) + config["args"]["sql"] = sql + config[bindings.KEY] = {"binder": bindings.BINDER, "version": 1, "domain": "order_sales", "mapping_version": 1, + "template": template, "snippets": copy.deepcopy(snippets), "values": dict(broken_values), + "rendered_hash": bindings.sql_hash(sql)} + assert bindings.shape_problem(config[bindings.KEY]) + + report = bindings.plan(graph, "card") + assert report.status == bindings.UNSUPPORTED and report.configs == {} + assert report.fix == bindings.FIX_AUTHOR and label in report.reason + assert "没有它" in report.reason + assert bindings.blocking(report) + assert bindings.snapshot_material(config, config["args"]) is None # 不记一份假的绑定材料 + with pytest.raises(bindings.UnresolvedToken): + bindings.render(template, snippets, broken_values) # 也不许把 [[…]] 原样留着 + + +async def test_a_broken_binding_keeps_the_definition_and_leaves_the_sql_alone(client): + """这条不自洽的绑定经真实 PATCH:定义照常保存,SQL 一个字不动(也不把 [[…]] 写回去),运行照样被拦。""" + graph = S.graph(values=S.OLD, metrics=S.card_metrics()) + config = fetch_config(graph) + broken = config[bindings.KEY] + broken["values"] = {"time_role": "order_time"} # 模板里的 [[refund_rule]] 没值了 + body = await S.draft(graph) + before_sql = config["args"]["sql"] + + res = await patch_biz(client, body, biz_ops()) + assert res.status_code == 200, res.text + change = res.json()["change"] + assert change["binding"]["synced"] is False and change["binding"]["status"] == bindings.UNSUPPORTED + assert "退款处理" in change["binding"]["unsupported_reason"] + after = await graph_of(body["workflow_id"]) + assert fetch_config(after)["args"]["sql"] == before_sql + assert "[[" not in fetch_config(after)["args"]["sql"] # 没把占位写回 SQL + assert card_metric(after, "m1")["refund_rule"] == "exclude_full_refund" # 定义存下来了 + + runs_before = await runs_of(body["workflow_id"]) + refused = await client.post(patch_url(body["id"]) + "/trial", json={"inputs": dict(S.OCTOBER)}) + assert refused.json()["status"] == "failed" and refused.json()["metrics"] == [] + assert "退款处理" in refused.json()["error"] + assert await runs_of(body["workflow_id"]) == runs_before + + +# ========================================================================== +# 声明了业务字段但定位不到取数节点:不能当成「没声明」放行 +# ========================================================================== + +def _unlocatable_graph(expression: str, *, extra_node: dict[str, Any] | None = None) -> dict: + """一张卡:取数节点照常有受控绑定,但指标的式子读不到它(读 code / merge 节点、读 vars……)。""" + graph = S.graph(values=S.NEW, metrics=[]) + card = next(node for node in graph["nodes"] if node["id"] == "card") + card["data"]["config"]["metrics"] = [ + {"id": "m1", "name": "订单数", "expression": expression, "time_role": "payment_time"}] + if extra_node is not None: + graph["nodes"].insert(2, extra_node) + return graph + + +@pytest.mark.parametrize("expression,extra_node,expected", [ + # 读沙箱代码节点的结果:那条 SQL 是别处来的,定位不到取数节点 + ("cell(nodes.code_1, 0, 'v')", S.node("code_1", "code", code="1"), "沙箱代码"), + # 读合并查询节点:同样不是取数节点 + ("cell(nodes.merge_1, 0, 'v')", S.node("merge_1", "merge", sql="SELECT 1 AS v"), "合并查询"), + # 式子读的是 vars/rows 这类拿不到节点身份的写法 + ("vars.total", None, "不是取数节点某一格"), +]) +def test_a_declaration_that_cannot_be_located_is_unsupported(expression, extra_node, expected): + """有声明、却定位不到它读的取数节点:unsupported(不是 unbound),保住 metric_values、原因和该做什么。""" + graph = _unlocatable_graph(expression, extra_node=extra_node) + report = bindings.analyze(graph, "card") + assert report.status == bindings.UNSUPPORTED and report.blocked + assert report.fix == bindings.FIX_AUTHOR + assert report.metric_values == {"m1": {"time_role": "payment_time"}} # 声明了什么,照实留着 + assert report.metrics == ("m1",) + assert "「m1」" in report.reason and expected in report.reason + assert "定位不到" in report.reason and bindings.blocking(report) + + # 同步不了,也不假装对齐:定义照旧、SQL 一个字不写 + assert bindings.plan(graph, "card").configs == {} + capability = bindings.capability(graph, "card") + assert capability["status"] == bindings.UNSUPPORTED and capability["metric_values"] == report.metric_values + assert capability["unsupported_reason"] == report.reason + + # 同一张卡上照常挂在取数节点上的指标(能定位的那种)不受牵连:这次两份声明都在,整体仍是 unsupported + both = copy.deepcopy(graph) + next(node for node in both["nodes"] if node["id"] == "card")["data"]["config"]["metrics"].append( + {"id": "m2", "name": "销售额", "expression": "cell(nodes.fetch, 0, 'amount')", "time_role": "payment_time"}) + mixed = bindings.analyze(both, "card") + assert mixed.status == bindings.UNSUPPORTED and mixed.metrics == ("m1", "m2") + assert [state.node_id for state in mixed.nodes] == ["fetch"] # 能定位的那个照常判 + assert mixed.nodes[0].status == bindings.ALIGNED # 这张图的取数就是按支付时间展开的 + assert mixed.metric_values["m2"] == {"time_role": "payment_time"} + + +async def test_an_unlocatable_declaration_blocks_the_raw_run_and_the_change(client): + """统一阻断:这种声明在原图直接运行和字段变更两条路上都拦住,一条 SQL 都不用发、也不落成「已同步」。""" + from app.engine.evidence_reader import metric_cards, read_sealed + from tests.ledger_samples import wait as wait_run + + graph = _unlocatable_graph("vars.total") + body = await S.draft(graph) + # 读接口:草稿页照实说 unsupported + 具体原因(不是 unbound) + shown = (await client.get(patch_url(body["id"]))).json() + assert shown["binding"]["status"] == bindings.UNSUPPORTED + assert "定位不到" in shown["binding"]["unsupported_reason"] + assert shown["binding"]["metric_values"] == {"m1": {"time_role": "payment_time"}} + + # 字段变更:定义照常保存,SQL 一个字不动,回执说清为什么没同步 + res = await patch_biz(client, body, [{"op": "set", "metric_id": "m1", "path": "/refund_rule", + "value": "exclude_full_refund"}]) + assert res.status_code == 200, res.text + change = res.json()["change"] + assert change["binding"]["synced"] is False and change["binding"]["status"] == bindings.UNSUPPORTED + assert "定位不到" in change["binding"]["unsupported_reason"] + after = await graph_of(body["workflow_id"]) + assert fetch_config(after)["args"]["sql"] == S.render(S.NEW) # 没被改写 + assert card_metric(after, "m1")["refund_rule"] == "exclude_full_refund" + + # 原图直接运行:算数之前停,一个数都没有 + run = await run_manager.start(graph=after, input_payload=dict(S.OCTOBER), run_class="exploratory", + origin_kind="chat", origin={"conversation_id": "k04-locate"}) + row = await wait_run(run.id) + assert row.status == "failed", row.error + assert "没有计算任何指标" in str(row.error) and "定位不到" in str(row.error) + assert list(metric_cards(await read_sealed(run.id))) == [] + + # 试跑也一样:派生那一步(derive.load_pinned)就拒,一条 SQL 都不发、运行表里不多行 + runs_before = await runs_of(body["workflow_id"]) + refused = await client.post(patch_url(body["id"]) + "/trial", json={"inputs": dict(S.OCTOBER)}) + assert refused.status_code == 200, refused.text + assert refused.json()["status"] == "failed" and refused.json()["metrics"] == [] + assert await runs_of(body["workflow_id"]) == runs_before + + +def test_normal_external_metrics_and_old_assets_are_not_harmed(): + """照旧不受影响的两类:没有业务声明的外部常量旧资产(unbound),以及和声明混在一起的外部常量指标。""" + # 只有外部常量、没有任何业务声明:unbound,不判同步、不拦 + external_only = S.graph(values=S.OLD, metrics=[{ + "id": "m1", "name": "预算", "kind": "external", + "external": {"source": "年度预算表", "as_of": "2026-01-01"}}]) + report = bindings.analyze(external_only, "card") + assert report.status == bindings.UNBOUND and not report.blocked + assert report.metric_values == {} and report.nodes == () + + # 外部常量 + 一个声明了业务字段的取数指标:只判取数那个,外部常量不算「定位不到」 + mixed = S.graph(values=S.NEW) + next(node for node in mixed["nodes"] if node["id"] == "card")["data"]["config"]["metrics"].append( + {"id": "m9", "name": "预算", "kind": "external", "external": {"source": "年度预算表"}}) + report = bindings.analyze(mixed, "card") + assert report.status == bindings.ALIGNED and not report.blocked + assert report.metrics == ("m1", "m2") and report.metric_values.get("m9") is None + assert [state.node_id for state in report.nodes] == ["fetch"] + + +# ========================================================================== +# 读接口:能力描述 +# ========================================================================== + +async def test_the_capability_description_lists_the_fields_the_values_and_the_state(client): + """口径描述接口给:能改哪些业务字段、允许值、现在的值、同步状态;不返回模板和 SQL。""" + workflow_id = await S.publish(S.graph(), name=f"{OWN_PREFIX}描述") + made = (await client.get(f"/api/ledger/calibers/{workflow_id}/1/card")).json() + block = made["binding"] + assert [field["field"] for field in block["editable_fields"]] == ["time_role", "refund_rule"] + time_role = block["editable_fields"][0] + assert time_role["values"] == ["order_time", "payment_time"] + assert time_role["value_labels"]["payment_time"] == "按支付时间" and time_role["label"] == "统计时间口径" + assert block["current"] == S.OLD and block["status"] == bindings.ALIGNED and block["checked"] is True + assert block["metric_values"] == {"m1": S.OLD, "m2": S.OLD} + assert set(block["binding_fingerprints"]) == {"fetch"} + dumped = str(made) + assert "[[time_role]]" not in dumped and "SELECT COUNT(*)" not in dumped # 不给模板、不给 SQL + + # 草稿页也给同一份(工作台按它决定展示哪些业务修改) + body = await S.draft(S.graph()) + shown = (await client.get(patch_url(body["id"]))).json() + assert shown["binding"]["current"] == S.OLD + assert [field["field"] for field in shown["binding"]["editable_fields"]] == ["time_role", "refund_rule"] + + # 同步不了的:读接口照实给 unsupported + 原因(不返回模板,也不假装对齐) + complex_wf = await S.publish(S.complex_graph(), name=f"{OWN_PREFIX}复杂描述") + complex_block = (await client.get(f"/api/ledger/calibers/{complex_wf}/1/card")).json()["binding"] + assert complex_block["status"] == bindings.UNSUPPORTED + assert "没有「统计时间口径」的落点" in complex_block["unsupported_reason"] + assert complex_block["fix"] == bindings.FIX_AUTHOR and complex_block["metrics"] == ["m1", "m2"] + + +async def test_aligned_never_means_verified(client): + """aligned 只说明定义和实现同步:语义审阅标记和质量结论不会因为它变成「通过」。""" + from app.engine.evidence_reader import metric_cards, read_sealed + + body = await S.draft(S.graph()) + assert (await client.get(patch_url(body["id"]))).json()["binding"]["status"] == bindings.ALIGNED + done = await trial(client, body) + assert done["status"] == "succeeded", done.get("error") + + # 封存的口径卡照旧标 semantic_unverified(业务描述和取数条件的一致性仍需审阅),质量结论是 unknown 不是 pass + sealed = await read_sealed(done["run_id"]) + computed = {metric["id"]: metric for _node, _artifact, card in metric_cards(sealed) + for metric in card.get("metrics") or []} + assert computed["m1"]["semantic_unverified"] is True and computed["m2"]["semantic_unverified"] is True + for metric in computed.values(): + assert metric["quality"]["status"] == "unknown" + assert any(check["code"] == "semantic_definition" for check in metric["quality"]["checks"]) + + +# ========================================================================== +# 旧资产:没有业务字段,照旧 +# ========================================================================== + +async def test_a_caliber_without_business_fields_keeps_its_old_behaviour(client): + """没有声明时间口径 / 退款规则的卡(绝大多数旧资产):状态 unbound、不拦、照旧跑。""" + graph = S.graph(values=S.OLD, metrics=S.card_metrics(time_role=None, refund_rule=None), with_binding=False) + body = await S.draft(graph) + shown = (await client.get(patch_url(body["id"]))).json() + assert shown["binding"]["status"] == bindings.UNBOUND + assert shown["binding"]["metric_values"] == {} and shown["binding"]["nodes"] == [] + + done = await trial(client, body) + assert done["status"] == "succeeded", done.get("error") + assert values_of(done) == {"m1": S.EXPECTED["old"]["orders"], "m2": S.EXPECTED["old"]["amount"]} + # 改别的字段照旧(不因为「没绑定」被拦) + res = await patch_biz(client, body, [{"op": "set", "metric_id": "m1", "path": "/unit", "value": "笔"}]) + assert res.status_code == 200, res.text + assert res.json()["change"]["binding"]["synced"] is False + assert res.json()["change"]["binding"]["status"] == bindings.UNBOUND + + # 一旦声明了业务字段,而取数节点上没有受控绑定:定义照常保存,但从此如实说 needs_update——不许再跑 + # (跑了也还是那条旧 SQL 算出来的数,那就是拿旧数冒充新定义) + before_sql = fetch_config(await graph_of(body["workflow_id"]))["args"]["sql"] + changed = await patch_biz(client, res.json(), biz_ops()) + assert changed.status_code == 200, changed.text + assert changed.json()["change"]["binding"]["status"] == bindings.NEEDS_UPDATE + assert changed.json()["change"]["binding"]["fix"] == bindings.FIX_AUTHOR + assert fetch_config(await graph_of(body["workflow_id"]))["args"]["sql"] == before_sql + runs_before = await runs_of(body["workflow_id"]) + refused = await client.post(patch_url(body["id"]) + "/trial", json={"inputs": dict(S.OCTOBER)}) + assert refused.json()["status"] == "failed" and refused.json()["metrics"] == [] + assert "没有受控绑定" in refused.json()["error"] + assert await runs_of(body["workflow_id"]) == runs_before + + +def test_an_unbound_node_that_declares_business_fields_is_needs_update(): + """节点上没有绑定、指标却声明了业务字段:如实说 needs_update + 该做什么(不假装对齐,也不猜 SQL)。""" + graph = S.graph(with_binding=False) + report = bindings.plan(graph, "card") + assert report.status == bindings.NEEDS_UPDATE and report.fix == bindings.FIX_AUTHOR + assert report.configs == {} and "没有受控绑定" in report.reason + assert bindings.blocking(report) diff --git a/backend/tests/test_caliber_closure.py b/backend/tests/test_caliber_closure.py new file mode 100644 index 00000000..ffabe09e --- /dev/null +++ b/backend/tests/test_caliber_closure.py @@ -0,0 +1,559 @@ +"""K08 的依赖闭包解析器(app/ledger/closure.py):S1 的解析、S2 的选择位置、S4 的摘要。 + +这一份**只按纯函数用**:不建库、不起引擎、不发模型请求(接线在 ledger/derive 与 ledger/compose——按选择裁要执行的取数 +与入口字段;运行时按口径卡上的 caliber_from.metrics 读 effective_metrics)。合成 A/B 两张卡的形状(两指标两张表的口径、 +指标类型)都在这里现搭,复用 tests/binding_samples 的受控模板与绑定写法。 + +覆盖任务书要的四类验收(§5 K08:A/B 独立、共享查询、全局约束、未知依赖),外加这里必须锁住的身份与确定性: + +- 选 A 时 B 独有且无依赖的查询与参数不进这次范围;共享的那条 SQL 保留,并显式声明它还在算未选中的 B + (computes_unselected),不做投影; +- 共享参数、卡 on_missing、图 defaults 照样带上; +- 未知指标 / 式子读不出来 / 引用不存在的节点 / 参数没声明 / 绑定对不上 → unresolved,require() 抛错,绝不静默退回整卡; +- 缺省整卡、显式整卡、显式空选择(不当整卡)、显式与整卡冲突(不放宽); +- 确定性、metric_ids 重排不影响结果; +- 两条 SQL 内容一样的节点不合并(不拿内容哈希当身份); +- query_id 跨版本稳定、改名会变、显式 query_id 改名也稳定;别名不是源身份(source 记真实节点与版本); +- 绑定变化只动 closure_hash:selection_hash 不变(绑定指纹不进它)。 +""" +from __future__ import annotations + +import copy + +import pytest + +from app.data.caliber_identity import card_hash_of +from app.ledger import bindings, closure +from tests import binding_samples as S + +#: 入口字段:start / end 是两张表都要的共享参数,store 只有 B 那张表要 +FIELDS = [{"name": "start", "type": "string", "required": True, "description": "开始日期(含)"}, + {"name": "end", "type": "string", "required": True, "description": "结束日期(不含)"}, + {"name": "store", "type": "string", "required": False, "description": "门店(B 那条查询要)"}] + +#: B 那张表比 A 多一个门店过滤(params 槽位:store 只有它用) +TEMPLATE_B = S.TEMPLATE + " AND o.store = '{{ input.store }}'" + + +def fetch(node_id: str, template: str = S.TEMPLATE, values: dict[str, str] | None = None, *, + query_id: str | None = None, binding: bool = True) -> dict: + """一个取数节点:受控模板按当前业务值展开成 args.sql,并写一份对得上的绑定。""" + values = dict(values or S.OLD) + sql = bindings.render(template, S.SNIPPETS, values) + config: dict = {"tool": S.tool(), "args": {"sql": sql}} + if binding: + config[bindings.KEY] = S.binding(values, template=template, sql=sql) + if query_id: + config["query_id"] = query_id + return S.node(node_id, "tool", **config) + + +def metric(metric_id: str, node_id: str, *, column: str = "orders", time_role: str | None = S.OLD["time_role"], + refund_rule: str | None = S.OLD["refund_rule"], **extra) -> dict: + made: dict = {"id": metric_id, "name": metric_id, "unit": "单", + "expression": f"cell(nodes.{node_id}, 0, '{column}')"} + if time_role: + made["time_role"] = time_role + if refund_rule: + made["refund_rule"] = refund_rule + made.update(extra) + return made + + +def graph(*, metrics: list[dict], fetches: list[dict], fields: list[dict] | None = None, + card_config: dict | None = None, defaults: dict | None = None) -> dict: + """入口 → 各条取数 → 口径卡 → 出口;defaults 给了就是图级 defaults。""" + made = S.chain(S.node("start", "input", fields=copy.deepcopy(fields if fields is not None else FIELDS)), + *copy.deepcopy(fetches), + S.node("card", "metrics", caliber="订单口径", caliber_version="v1", + metrics=copy.deepcopy(metrics), **copy.deepcopy(card_config or {})), + S.node("out", "output", fields=[{"name": "结果", "value": "{{ nodes.card.text }}"}])) + if defaults: + made["defaults"] = copy.deepcopy(defaults) + return made + + +def _metrics_for(values: dict[str, str], pairs: list[tuple[str, str]]) -> list[dict]: + """按当前业务值给指标声明(定义和那份 SQL 自洽):换个 values 就是自洽的新一版。""" + return [metric(metric_id, node_id, time_role=values.get("time_role"), + refund_rule=values.get("refund_rule")) for metric_id, node_id in pairs] + + +def graph_ab(*, values: dict[str, str] | None = None, card_config: dict | None = None, + defaults: dict | None = None) -> dict: + """A 读 q_a、B 读 q_b:两条独立查询;store 只有 B 用。默认两张表都和定义同步。""" + values = dict(values or S.OLD) + return graph(metrics=_metrics_for(values, [("a", "q_a"), ("b", "q_b")]), + fetches=[fetch("q_a", S.TEMPLATE, values), fetch("q_b", TEMPLATE_B, values)], + card_config=card_config, defaults=defaults) + + +def graph_shared(*, values: dict[str, str] | None = None, card_config: dict | None = None, + defaults: dict | None = None) -> dict: + """A 和 B 读同一条取数(共享 SQL):一条 SQL 上两个指标。""" + values = dict(values or S.OLD) + return graph(metrics=_metrics_for(values, [("a", "q_shared"), ("b", "q_shared")]), + fetches=[fetch("q_shared", S.TEMPLATE, values)], + card_config=card_config, defaults=defaults) + + +def codes(problems) -> list[str]: + return [p["code"] for p in problems] + + +# ========================================================================== +# A/B 独立:选 A 不带 B 的查询和参数 +# ========================================================================== + + +def test_independent_selection_drops_the_other_metrics_query_and_params(): + """A/B 独立:选 A 只要 q_a,q_b 排除;store 只有 B 用,不算这次要的参数。""" + made = graph_ab() + whole = closure.build(made, "wf-ab", 1, "card").require() + assert whole.mode == closure.WHOLE_CARD and whole.whole_card + assert whole.card_metric_ids == ("a", "b") and whole.metric_ids == ("a", "b") + assert whole.query_ids == ("wf-ab:q_a", "wf-ab:q_b") and whole.excluded_query_ids == () + assert [f["name"] for f in whole.required_entry_fields] == ["start", "end", "store"] + + a = closure.build(made, "wf-ab", 1, "card", metric_ids=["a"]).require() + assert a.mode == closure.EXPLICIT and not a.whole_card + assert a.card_metric_ids == ("a", "b") and a.metric_ids == ("a",) + assert a.query_ids == ("wf-ab:q_a",) and a.excluded_query_ids == ("wf-ab:q_b",) + assert [f["name"] for f in a.required_entry_fields] == ["start", "end"] # store 被排除 + assert a.entry_fields and [f["name"] for f in a.entry_fields] == ["start", "end", "store"] + assert a.metric_query_ids("a") == ["wf-ab:q_a"] and a.metric_query_ids("b") == [] + assert [q.computes_unselected for q in a.queries] == [()] # q_a 只算 A + assert a.binding_fingerprints and set(a.binding_fingerprints) == {"wf-ab:q_a"} + + b = closure.build(made, "wf-ab", 1, "card", metric_ids=["b"]).require() + assert b.query_ids == ("wf-ab:q_b",) and b.excluded_query_ids == ("wf-ab:q_a",) + assert [f["name"] for f in b.required_entry_fields] == ["start", "end", "store"] + + +def test_selection_is_normalized_by_source_card_order(): + """显式选择按源卡顺序归一:调用方传的顺序和重复项都不影响结果。""" + made = graph_ab() + forward = closure.build(made, "wf-ab", 1, "card", metric_ids=["a", "b"]).require() + reverse = closure.build(made, "wf-ab", 1, "card", metric_ids=["b", "a", "b"]).require() + assert forward.metric_ids == reverse.metric_ids == ("a", "b") + assert forward.query_ids == reverse.query_ids + assert forward.selection_hash == reverse.selection_hash + assert forward.closure_hash == reverse.closure_hash + assert forward.as_dict() == reverse.as_dict() + + +# ========================================================================== +# 共享查询:保留了就要声明它还在算谁 +# ========================================================================== + + +def test_a_shared_query_is_kept_and_declares_what_it_still_computes(): + """共享 SQL 选 A 也保留,并显式声明它还在算未选中的 B;共享参数一并保留(不做投影)。""" + made = graph_shared() + a = closure.build(made, "wf-shared", 1, "card", metric_ids=["a"]).require() + assert a.metric_ids == ("a",) and a.query_ids == ("wf-shared:q_shared",) and a.excluded_query_ids == () + shared = a.queries[0] + assert shared.metric_ids == ("a",) and shared.computes_unselected == ("b",) + # 共享参数照样要(这条 SQL 用 start/end 渲染):共享约束不能被裁掉 + assert [f["name"] for f in a.required_entry_fields] == ["start", "end"] + assert a.binding_fingerprints # 共享节点上的绑定指纹还在 + + whole = closure.build(made, "wf-shared", 1, "card").require() + assert [q.computes_unselected for q in whole.queries] == [()] # 整卡模式下没有「未选中」 + + +def test_two_nodes_with_the_same_sql_stay_two_queries(): + """不拿内容哈希当身份:两条 SQL 一字不差,也是两条查询(不合并、各有各的 query_id)。""" + made = graph(metrics=[metric("a", "q_a"), metric("b", "q_b")], + fetches=[fetch("q_a", S.TEMPLATE), fetch("q_b", S.TEMPLATE)]) + assert made["nodes"][1]["data"]["config"]["args"]["sql"] == made["nodes"][2]["data"]["config"]["args"]["sql"] + got = closure.build(made, "wf-same", 1, "card").require() + assert got.query_ids == ("wf-same:q_a", "wf-same:q_b") + assert [q.sql_hash for q in got.queries][0] == [q.sql_hash for q in got.queries][1] + assert [q.node_id for q in got.queries] == ["q_a", "q_b"] + + +# ========================================================================== +# 全局约束:图 defaults、卡 on_missing +# ========================================================================== + + +def test_global_constraints_travel_with_the_selection(): + """选一小部分指标也要带上图 defaults 与卡的「缺输入时」——那是全局必要约束,不被裁剪。""" + made = graph_ab(card_config={"on_missing": "null"}, defaults={"tool": S.tool(), "args": {"limit": 500}}) + a = closure.build(made, "wf-cfg", 1, "card", metric_ids=["a"]).require() + assert a.on_missing == "null" + assert a.defaults == {"tool": S.tool(), "args": {"limit": 500}} + assert a.as_dict()["on_missing"] == "null" and a.as_dict()["defaults"]["args"]["limit"] == 500 + + +# ========================================================================== +# 零查询:external 指标没有取数,但不是未决项 +# ========================================================================== + + +def test_an_external_metric_needs_no_query_and_is_not_unresolved(): + """external 型指标本来就不查库:进 metric_ids,query_ids 为空,unresolved 为空。""" + made = graph(metrics=[metric("a", "q_a"), + {"id": "e", "name": "e", "kind": "external", + "external": {"value": 1.5, "source": "监管口径", "as_of": "2026-10-01"}}], + fetches=[fetch("q_a", S.TEMPLATE)]) + whole = closure.build(made, "wf-ext", 1, "card").require() + assert whole.metric_ids == ("a", "e") + assert whole.query_ids == ("wf-ext:q_a",) + assert whole.queries[0].metric_ids == ("a",) + assert [q.computes_unselected for q in whole.queries] == [()] + assert whole.unresolved == () + + only_external = graph(metrics=[{"id": "e", "name": "e", "kind": "external", + "external": {"value": 1, "source": "监管口径", "as_of": "2026-10-01"}}], + fetches=[fetch("q_a", S.TEMPLATE)]) + empty = closure.build(only_external, "wf-ext", 1, "card", metric_ids=["e"]).require() + assert empty.metric_ids == ("e",) and empty.query_ids == () and empty.excluded_query_ids == () + + +# ========================================================================== +# 未知依赖:进 unresolved,require() 抛错,绝不静默整卡 +# ========================================================================== + + +def test_an_unknown_metric_is_unresolved_and_never_falls_back_to_the_whole_card(): + made = graph_ab() + got = closure.build(made, "wf-unknown", 1, "card", metric_ids=["a", "没有这个"]) + assert [p["code"] for p in got.unresolved] == [closure.METRIC_UNKNOWN] + assert got.unresolved[0]["metric_id"] == "没有这个" + assert got.metric_ids == ("a",) # 只按点名的那一个走,不放大成整卡 + assert got.whole_card is False + with pytest.raises(closure.UnresolvedClosure) as raised: + got.require() + assert raised.value.problems == got.unresolved + + +def test_an_unknown_node_reference_is_unresolved(): + made = graph(metrics=[metric("a", "ghost")], fetches=[fetch("q_a", S.TEMPLATE)]) + got = closure.build(made, "wf-ghost", 1, "card") + assert codes(got.unresolved) == [closure.UNKNOWN_NODE] + assert got.unresolved[0]["node_id"] == "ghost" + assert got.query_ids == () + with pytest.raises(closure.UnresolvedClosure): + got.require() + + +def test_a_metric_with_an_unreadable_definition_is_unresolved(): + """kind 不认识(或该类型下式子是空的):解析不了依赖,直接未决,不猜。""" + made = graph(metrics=[metric("a", "q_a", kind="nope")], fetches=[fetch("q_a", S.TEMPLATE)]) + got = closure.build(made, "wf-bad", 1, "card") + assert codes(got.unresolved) == [closure.EXPRESSION_UNREADABLE] + assert got.unresolved[0]["metric_id"] == "a" and got.query_ids == () + + +def test_an_undeclared_parameter_is_unresolved(): + """SQL 引用了入口没声明的参数:未决,不按空串发出去(K01 的同一套判定)。""" + made = graph(metrics=[metric("a", "q_a")], + fetches=[fetch("q_a", S.TEMPLATE + " AND o.region = '{{ input.region }}'")]) + got = closure.build(made, "wf-param", 1, "card") + assert closure.UNDECLARED_PARAMETER in codes(got.unresolved) + assert [f["name"] for f in got.required_entry_fields] == ["start", "end"] + + +def test_an_unaligned_binding_is_unresolved_but_only_for_the_selected_metrics(): + """K04 的定义 vs 绑定对不上:整卡未决;只选 A 时,B 那条对不上的查询不牵连 A。""" + made = graph(metrics=[metric("a", "q_a"), + # B 的定义已经改成支付时间,q_b 那条 SQL 还停在按下单时间:对不上 + metric("b", "q_b", time_role="payment_time", refund_rule="exclude_full_refund")], + fetches=[fetch("q_a", S.TEMPLATE), fetch("q_b", TEMPLATE_B)]) + whole = closure.build(made, "wf-align", 1, "card") + assert codes(whole.unresolved) == [closure.BINDING_UNRESOLVED] + assert whole.unresolved[0]["node_id"] == "q_b" + with pytest.raises(closure.UnresolvedClosure): + whole.require() + + a = closure.build(made, "wf-align", 1, "card", metric_ids=["a"]).require() + assert a.unresolved == () and a.query_ids == ("wf-align:q_a",) and a.excluded_query_ids == ("wf-align:q_b",) + + +def test_a_conflict_on_a_shared_query_is_only_reported_when_the_other_metric_is_selected(): + """同一条共享 SQL 上两个指标说法打架:整卡未决;只选 A(且 A 的说法就是 SQL 现在的说法)时不牵连 A。 + + 这是有意的分寸:共享 SQL 只是「还算了 B」——如实写进 computes_unselected,B 的数不交回,A 的结论不受 B 的 + 说法牵连(反例「B 独有错误导致 A 失败」)。""" + made = graph(metrics=[metric("a", "q_shared"), + metric("b", "q_shared", time_role="payment_time", + refund_rule="exclude_full_refund")], + fetches=[fetch("q_shared", S.TEMPLATE)]) + whole = closure.build(made, "wf-conflict", 1, "card") + assert closure.BINDING_UNRESOLVED in codes(whole.unresolved) + + a = closure.build(made, "wf-conflict", 1, "card", metric_ids=["a"]).require() + assert a.queries[0].computes_unselected == ("b",) + assert a.binding_fingerprints and set(a.binding_fingerprints) == {"wf-conflict:q_shared"} + + +def test_a_chained_card_cannot_be_resolved_without_the_pinned_definitions(): + """转抄别处的卡(caliber_from)本图里没有定义:照实说未决,不假装解析出依赖。""" + made = graph_ab() + card = next(n for n in made["nodes"] if n["id"] == "card") + card["data"]["config"].pop("metrics") + card["data"]["config"]["caliber_from"] = {"workflow_id": "up", "workflow_version": 2, "node_id": "card"} + got = closure.build(made, "wf-chain", 1, "card") + assert codes(got.unresolved) == [closure.CARD_CHAINED] + assert got.card_metric_ids == () and got.query_ids == () + + +# ========================================================================== +# 整卡与空选择 +# ========================================================================== + + +def test_explicit_whole_card_and_an_empty_selection_are_different_things(): + made = graph_ab() + whole = closure.build(made, "wf-mode", 1, "card", whole_card=True).require() + assert whole.mode == closure.WHOLE_CARD and whole.whole_card and whole.metric_ids == ("a", "b") + assert whole.excluded_query_ids == () + + empty = closure.build(made, "wf-mode", 1, "card", metric_ids=[]) + assert codes(empty.unresolved) == [closure.EMPTY_SELECTION] + assert empty.metric_ids == () and empty.whole_card is False # 空选择不当整卡 + with pytest.raises(closure.UnresolvedClosure): + empty.require() + + +def test_asking_for_both_is_reported_and_does_not_widen_anything(): + made = graph_ab() + both = closure.build(made, "wf-both", 1, "card", metric_ids=["a"], whole_card=True) + assert closure.CONFLICTING_SELECTION in codes(both.unresolved) + assert both.metric_ids == ("a",) and both.whole_card is False # 冲突时按更窄的一边 + assert both.excluded_query_ids == ("wf-both:q_b",) + with pytest.raises(closure.UnresolvedClosure): + both.require() + + +def test_an_empty_card_in_whole_card_mode_is_unresolved(): + made = graph(metrics=[], fetches=[fetch("q_a", S.TEMPLATE)]) + got = closure.build(made, "wf-empty", 1, "card") + assert codes(got.unresolved) == [closure.CARD_EMPTY] and got.query_ids == () + + +# ========================================================================== +# 身份:query_id、source、整卡指纹 +# ========================================================================== + + +def test_query_id_is_stable_across_versions_and_changes_on_rename(): + """query_id 是逻辑身份:不随版本变;节点改名会变;显式 query_id 改名也稳定;别名不是源身份。""" + made = graph_ab() + v1 = closure.build(made, "wf-id", 1, "card").require() + v9 = closure.build(made, "wf-id", 9, "card").require() + assert v1.query_ids == v9.query_ids == ("wf-id:q_a", "wf-id:q_b") + assert v1.source == {"workflow_id": "wf-id", "version": 1, "card_id": "card"} + assert v9.source["version"] == 9 and v9.selection_hash != v1.selection_hash + + renamed = graph_ab() + next(n for n in renamed["nodes"] if n["id"] == "q_a")["id"] = "q_a_renamed" + next(n for n in renamed["nodes"] if n["id"] == "card")["data"]["config"]["metrics"][0]["expression"] = \ + "cell(nodes.q_a_renamed, 0, 'orders')" + after = closure.build(renamed, "wf-id", 1, "card").require() + assert after.query_ids == ("wf-id:q_a_renamed", "wf-id:q_b") + + # 节点上显式声明 query_id(别名):改名之后逻辑身份不变,但 source 记的是真实节点 + aliased = graph_ab() + next(n for n in aliased["nodes"] if n["id"] == "q_a")["data"]["config"]["query_id"] = "orders_total" + one = closure.build(aliased, "wf-id", 3, "card", metric_ids=["a"]).require() + assert one.query_ids == ("orders_total",) + assert one.queries[0].source == {"workflow_id": "wf-id", "version": 3, "node_id": "q_a"} + assert one.queries[0].node_id == "q_a" and one.queries[0].query_id == "orders_total" + assert closure.query_id_of("wf-id", "q_a", {"query_id": "orders_total"}) == "orders_total" + assert closure.query_id_of("wf-id", "q_a", {}) == "wf-id:q_a" + + +def test_two_queries_with_the_same_logical_identity_are_unresolved(): + made = graph(metrics=[metric("a", "q_a")], + fetches=[fetch("q_a", S.TEMPLATE, query_id="orders"), + fetch("q_b", TEMPLATE_B, query_id="orders")]) + got = closure.build(made, "wf-dup", 1, "card", metric_ids=["a"]) + assert closure.DUPLICATE_QUERY_ID not in codes(got.unresolved) # q_b 没被选中,不进这次范围 + both = graph(metrics=[metric("a", "q_a"), metric("b", "q_b")], + fetches=[fetch("q_a", S.TEMPLATE, query_id="orders"), + fetch("q_b", TEMPLATE_B, query_id="orders")]) + dup = closure.build(both, "wf-dup", 1, "card") + assert codes(dup.unresolved) == [closure.DUPLICATE_QUERY_ID] + assert dup.unresolved[0]["query_id"] == "orders" + + +def test_the_source_card_hash_covers_the_whole_card_not_the_selection(): + """整卡身份(source_card_hash)和本次选择身份(selection_hash)都可追踪:选一半,整卡指纹不变。""" + made = graph_ab() + whole = closure.build(made, "wf-hash", 1, "card").require() + part = closure.build(made, "wf-hash", 1, "card", metric_ids=["a"]).require() + card = next(n for n in made["nodes"] if n["id"] == "card")["data"]["config"] + expected = card_hash_of({"metrics": card["metrics"], "caliber": card["caliber"], + "caliber_version": card["caliber_version"]}) + assert whole.source_card_hash == part.source_card_hash == expected + assert whole.selection_hash != part.selection_hash and whole.closure_hash != part.closure_hash + + +# ========================================================================== +# 跨指标契约:照实列出来,选一半时不悄悄丢掉 +# ========================================================================== + + +def test_cross_metric_contracts_are_listed(): + """选中指标声明的比例契约、图上出具契约点名的指标,都在 contract_dependencies 里如实列出。""" + made = graph_ab(card_config={"on_missing": "null"}) + card = next(n for n in made["nodes"] if n["id"] == "card") + card["data"]["config"]["metrics"][0]["contract"] = { + "shape": "scalar", "ratio": {"numerator": "orders", "denominator": "total"}} + out = next(n for n in made["nodes"] if n["id"] == "out") + out["data"]["config"]["contract"] = {"metrics_from": "card", "required": ["a", "b"]} + + a = closure.build(made, "wf-contract", 1, "card", metric_ids=["a"]).require() + assert a.contract_dependencies == ( + {"kind": "ratio", "metric_id": "a", "numerator": "orders", "denominator": "total"}, + {"kind": "report_contract", "node_id": "out", "metric_ids": ["a", "b"], "unselected": ["b"]}, + ) + whole = closure.build(made, "wf-contract", 1, "card").require() + assert whole.contract_dependencies[1]["unselected"] == [] # 整卡模式下没有「没选中的」 + + +# ========================================================================== +# 确定性与绑定变化 +# ========================================================================== + + +def test_the_same_input_always_gives_the_same_closure(): + made = graph_ab(card_config={"on_missing": "null"}, defaults={"x": 1}) + first = closure.build(made, "wf-det", 2, "card", metric_ids=["a", "b"]) + second = closure.build(copy.deepcopy(made), "wf-det", 2, "card", metric_ids=["b", "a"]) + assert first.as_dict() == second.as_dict() + assert first.selection_hash == second.selection_hash and first.closure_hash == second.closure_hash + + +def test_a_binding_change_moves_closure_hash_but_not_selection_hash(): + """同一份选择、同一批查询,绑定(业务值)从旧定义同步到新定义:selection_hash 不变,closure_hash 变。""" + old = closure.build(graph_shared(values=S.OLD), "wf-bind", 2, "card", metric_ids=["a"]).require() + new = closure.build(graph_shared(values=S.NEW), "wf-bind", 2, "card", metric_ids=["a"]).require() + assert old.metric_ids == new.metric_ids == ("a",) + assert old.query_ids == new.query_ids == ("wf-bind:q_shared",) + assert old.binding_fingerprints != new.binding_fingerprints + assert old.selection_hash == new.selection_hash # 绑定指纹不进 selection_hash + assert old.closure_hash != new.closure_hash # 但它进 closure_hash + assert old.source_card_hash != new.source_card_hash + + +# ========================================================================== +# 输入本身不可用:抛 ClosureRefused(不是 unresolved) +# ========================================================================== + + +@pytest.mark.parametrize("call", [ + lambda: closure.build(None, "wf", 1, "card"), + lambda: closure.build(graph_ab(), "wf", 1, "没有这张卡"), + lambda: closure.build(graph_ab(), "wf", "不是版本", "card"), + lambda: closure.build(graph_ab(), "wf", 1, "out"), # 不是口径卡 + lambda: closure.build(graph_ab(), "wf", 1, "card", metric_ids="a"), +]) +def test_bad_inputs_are_refused(call): + with pytest.raises(closure.ClosureRefused): + call() + + +def test_a_duplicated_metric_id_is_unresolved_and_never_resolves_to_one_of_them(): + """同一张卡上两个指标用同一个 id、各读一条查询:整卡与点名都未决(duplicate_metric_id)、require 失败。 + + 不能出现「闭包取最后那一份、运行时取第一份」:重复的 id 说不清算的是哪一个,所以哪种模式都照实报(K08 复核)。""" + made = graph(metrics=[metric("a", "q_a"), metric("a", "q_b")], + fetches=[fetch("q_a", S.TEMPLATE), fetch("q_b", TEMPLATE_B)]) + whole = closure.build(made, "wf-dup-metric", 1, "card") + assert codes(whole.unresolved) == [closure.DUPLICATE_METRIC_ID] + assert whole.unresolved[0]["metric_id"] == "a" and "重复" in whole.unresolved[0]["message"] + with pytest.raises(closure.UnresolvedClosure): + whole.require() + # 点名这个 id 也说不清算的是哪一份:照样未决(不静默挑一个) + one = closure.build(made, "wf-dup-metric", 1, "card", metric_ids=["a"]) + assert codes(one.unresolved) == [closure.DUPLICATE_METRIC_ID] + with pytest.raises(closure.UnresolvedClosure): + one.require() + # 卡上另一个(不重的)id 也照实拒:这是卡的身份问题,不是某个指标的问题 + other = graph(metrics=[metric("a", "q_a"), metric("a", "q_b"), metric("b", "q_b")], + fetches=[fetch("q_a", S.TEMPLATE), fetch("q_b", TEMPLATE_B)]) + assert codes(closure.build(other, "wf-dup-metric", 1, "card", metric_ids=["b"]).unresolved) \ + == [closure.DUPLICATE_METRIC_ID] + # 判定只有这一处:空 id 不算重复,重复的按第一次出现的先后只报一次 + assert closure.duplicate_metric_ids([metric("a", "q_a"), metric("a", "q_b"), {"name": "没有 id"}, metric("a", "q_c"), + metric("b", "q_c")]) == ["a"] + + +# ========================================================================== +# 这次算哪些指标:选择在源卡里的位置(运行时统一的那一份) +# ========================================================================== + + +def test_effective_metrics_keeps_the_source_card_order_and_reports_unknowns(): + """按卡上记的选择筛定义:保持源卡相对顺序,调用方传的顺序与重复项都不影响;认不出的 id 照实交回。""" + definitions = [metric("a", "q_a"), metric("b", "q_b"), metric("c", "q_c")] + index = closure.selection_index(definitions, ["c", "a", "c", "没有这个"]) + assert [d["id"] for d in index.definitions] == ["a", "c"] + assert index.positions == (0, 2) and index.metric_ids == ("a", "c") + assert index.unknown == ("没有这个",) and index.whole_card is False + assert index.as_dict() == {"metric_ids": ["a", "c"], "positions": [0, 2], "whole_card": False, + "unknown": ["没有这个"]} + assert [d["id"] for d in closure.effective_metrics(definitions, ["c", "a"])] == ["a", "c"] + assert closure.effective_metrics(definitions, ["c", "a"]) == closure.effective_metrics(definitions, ["a", "c"]) + # 交回的是源卡里的那几条定义本身(不是拷贝):运行时拿它算,别的键一个不动 + assert closure.effective_metrics(definitions, ["c", "a"]) == [definitions[0], definitions[2]] + + +def test_no_selection_is_the_whole_card_and_an_empty_one_selects_nothing(): + """不给选择就是整卡(顺序与条目一个不动);显式空选择是一个也不选,不静默当整卡。""" + definitions = [metric("a", "q_a"), {"name": "没有 id 的一条"}] + whole = closure.selection_index(definitions) + assert whole.whole_card and whole.positions == (0, 1) and whole.unknown == () + assert closure.effective_metrics(definitions) == definitions + assert closure.effective_metrics(definitions, ["a"]) == [definitions[0]] + empty = closure.selection_index(definitions, []) + assert empty.definitions == () and empty.positions == () and empty.whole_card is False + assert empty.unknown == () and closure.effective_metrics(definitions, []) == [] + + +def test_a_repeated_metric_id_in_the_card_is_taken_once(): + """同一张卡上重复的 id 只算第一次那个(口径卡的 id 该唯一;这一层不替它去重之后算两遍)。""" + first, second = metric("a", "q_a"), metric("a", "q_b") + index = closure.selection_index([first, second, metric("b", "q_c")], ["a", "b"]) + assert [d["id"] for d in index.definitions] == ["a", "b"] and index.positions == (0, 2) + assert index.definitions[0] is first + + +# ========================================================================== +# 闭包摘要(S4):身份、查询、字段、指纹各一份,但没有 SQL +# ========================================================================== + + +def test_the_summary_carries_the_identity_without_any_sql(): + """闭包摘要(K08 S4)给目录、选用选项与口径描述读:identity 与依赖全在,**没有 SQL 正文、没有参数值**。""" + import json + + got = closure.build(graph_ab(), "wf-summary", 3, "card", metric_ids=["a"]).require() + summary = got.summary() + assert summary["mode"] == closure.EXPLICIT and summary["whole_card"] is False + assert summary["metric_ids"] == ["a"] and summary["card_metric_ids"] == ["a", "b"] + assert summary["query_ids"] == ["wf-summary:q_a"] and summary["excluded_query_ids"] == ["wf-summary:q_b"] + assert summary["required_entry_fields"] == ["start", "end"] + [query] = summary["queries"] + assert query["query_id"] == "wf-summary:q_a" and query["node_id"] == "q_a" + assert query["metric_ids"] == ["a"] and query["computes_unselected"] == [] + assert query["required_entry_fields"] == ["start", "end"] and query["sql_hash"] == got.queries[0].sql_hash + assert summary["binding_fingerprints"] == dict(got.binding_fingerprints) and got.binding_fingerprints + assert summary["selection_hash"] == got.selection_hash and summary["closure_hash"] == got.closure_hash + assert summary["source_card_hash"] == got.source_card_hash and summary["unresolved"] == [] + assert summary["resolver_version"] == closure.RESOLVER_VERSION + # 整卡那一份也照样给(不点名:本次默认那份) + whole = closure.build(graph_ab(), "wf-summary", 3, "card").require().summary() + assert whole["whole_card"] is True and whole["query_ids"] == ["wf-summary:q_a", "wf-summary:q_b"] + # 摘要里没有 SQL 正文与参数值:条目是白的(从模板里挑几个一定只在 SQL 里出现的字) + blob = json.dumps([summary, whole], ensure_ascii=False) + bad = [n for n in ("SUM(", "FROM", "input.start", "{{", '"sql"', "refund_state") if n in blob] + assert bad == [], blob + # 交回的是新的一份,不把闭包内部的对象漏出去 + assert summary["queries"][0] is not got.queries[0] + assert summary["queries"][0] is not whole["queries"][0] + assert got.queries[0].sql_hash and "SUM(" in graph_ab()["nodes"][1]["data"]["config"]["args"]["sql"] diff --git a/backend/tests/test_caliber_draft_reads.py b/backend/tests/test_caliber_draft_reads.py new file mode 100644 index 00000000..826fee79 --- /dev/null +++ b/backend/tests/test_caliber_draft_reads.py @@ -0,0 +1,338 @@ +"""已接管草稿按图读、老草稿如实说没有来源基线(K03/K05 的前置边界)。 + +试跑(POST /api/ledger/drafts/{id}/trial)对 docattach 那种已接管草稿(tags 有 doc_draft、origin 里没有 kind)读的是 +**当前图版本**和**当前图里的入口字段**,不是 payload 里起草/接上那一刻的快照: + +- 图上有、payload 里没有的字段能填;payload 里的旧字段名现在是「不认识的入口字段」(422); +- 必填字段没给值 → needs_input,**一条 SQL 都不发**(运行表里不多一行); +- 数来自当前版本(v2)的 SQL,不是 payload 里写的那一版; +- 跑完试跑不判 stale(它记的就是当前这一版)。 + +来源基线(K05 的读取侧):草稿详情对没有可还原快照的老草稿如实给 baseline_unknown(不拿它现在的内容冒充「上次被 +接受的导入值」);payload 里已经有的快照和基线照原样交回,不重算、不另补。 + +真引擎跑一次(run_manager.setup + tests/ledger_samples 的真实 SQLite 店铺库):探针图里没有报告节点,不发模型请求。 +""" +from __future__ import annotations + +import copy +import uuid + +import pytest +from sqlalchemy import delete, func, select + +from app.core.artifact_store import graph_hash +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, Run, Workflow, WorkflowVersion +from app.engine.runner import run_manager +from tests import ledger_samples as S +from tests.test_ledger_docdraft_api import client # noqa: F401 - fixture 和起草用例共用 + +#: 这个文件自己建的工作流(连同版本、草稿)跑完删掉 +OWN_PREFIX = "K03 读真源 " + + +@pytest.fixture(autouse=True) +async def cleanup_own_rows(): + yield + async with SessionLocal() as session: + workflow_ids = list((await session.execute( + select(Workflow.id).where(Workflow.name.like(f"{OWN_PREFIX}%")))).scalars()) + if workflow_ids: + for model in (WorkflowVersion, CaliberDraft): + await session.execute(delete(model).where(model.workflow_id.in_(workflow_ids))) + await session.execute(delete(Workflow).where(Workflow.id.in_(workflow_ids))) + await session.commit() + + +#: 取数 SQL 里的那个加数:v2 比 v1 多 1000,跑出来的数一眼看得出是哪一版 +BUMP = 1000.0 + + +def graph(sql: str, *, fields: list[dict] | None = None) -> dict: + """一份能派生探针的口径图:入口 → 取数 → 口径卡(入口字段照给,缺省是 start / end 两个必填)。""" + return S.chain( + S.node("start", "input", fields=fields if fields is not None else [ + {"name": "start", "required": True, "description": "开始日期"}, + {"name": "end", "required": True, "description": "结束日期"}]), + S.node("fetch", "tool", tool=S.tool(), args={"sql": sql}), + S.node("card", "metrics", caliber="周销售", caliber_version="v1", + metrics=[{"id": "gmv", "name": "销售额", "unit": "元", "decimals": 2, + "expression": "cell(nodes.fetch, 0, 'gmv')"}]), + ) + + +async def attached_draft(*, graph: dict, payload: dict) -> dict: + """一份像 docattach 产物那样已接管、但 payload 还停在旧快照上的草稿(tags 有 doc_draft、origin 没有 kind)。""" + workflow_id = f"wf-{uuid.uuid4().hex[:12]}" + draft_id = uuid.uuid4().hex[:32] + async with SessionLocal() as session: + session.add(Workflow(id=workflow_id, name=f"{OWN_PREFIX}{uuid.uuid4().hex[:6]}", status="draft", graph=graph, + version=1, tags=["doc_draft"], + origin={"run_id": "run-1", "freeze": True, "sources": [{"run_id": "run-1"}]})) + session.add(WorkflowVersion(workflow_id=workflow_id, version=1, graph=graph, graph_hash=graph_hash(graph))) + await session.flush() # 草稿的外键指着工作流:先落工作流那一行 + session.add(CaliberDraft(id=draft_id, title="接上来的口径", status="ready", workflow_id=workflow_id, + payload={"version": 1, "workflow_id": workflow_id, **copy.deepcopy(payload)})) + await session.commit() + return {"id": draft_id, "workflow_id": workflow_id, "revision": 1, "card_id": "card"} + + +async def runs_of(workflow_id: str) -> int: + async with SessionLocal() as session: + return int(await session.scalar(select(func.count(Run.id)).where(Run.workflow_id == workflow_id)) or 0) + + +# ========================================================================== +# 试跑:当前图版本、当前入口字段、缺参不发 SQL +# ========================================================================== + +async def test_the_trial_of_a_taken_over_draft_reads_the_current_graph_not_the_payload(client, tmp_path): + """docattach 那种已接管草稿:试跑按当前图版本和当前入口字段跑,payload 里的旧快照一个字都不算数。""" + await run_manager.setup() + try: + await S.fresh_source(tmp_path / "shop.db") + # 起草/接上那一刻的 payload:入口字段是 store,版本停在 1,SQL 是另一句(跑到它身上一眼看得出) + body = await attached_draft( + graph=graph(S.TEMPLATE), payload={ + "sql": "SELECT 1 AS gmv", "entry_fields": [{"name": "store", "description": "旧快照里的字段"}], + "metrics": [{"id": "m1", "name": "旧指标", "expression": "cell(nodes.fetch, 0, 'gmv')"}]}) + + # 画布上改了取数(加了 1000):新的图版本就是当前这一版 + saved = await client.patch(f"/api/workflows/{body['workflow_id']}", json={ + "graph": graph(S.TEMPLATE.replace("SELECT SUM(amount) AS gmv", f"SELECT SUM(amount) + {BUMP} AS gmv")), + "expected_revision": body["revision"]}) + assert saved.status_code == 200, saved.text + assert saved.json()["version"] == 2 + + # 入口字段按图里的:payload 里那个旧字段现在是不认识的字段(不回退旧快照) + stale_field = await client.post(f"/api/ledger/drafts/{body['id']}/trial", + json={"inputs": {"store": "east", "start": "2026-09-01", "end": "2026-09-08"}}) + assert stale_field.status_code == 422, stale_field.text + assert "不认识的入口字段" in stale_field.text and "store" in stale_field.text + + # 必填没给:表单校验就拒(422,和别的入口同一套),一条 SQL 都不发(运行表里不多行) + before = await runs_of(body["workflow_id"]) + missing = await client.post(f"/api/ledger/drafts/{body['id']}/trial", json={"inputs": {}}) + assert missing.status_code == 422, missing.text + assert "start" in missing.text and "end" in missing.text + assert await runs_of(body["workflow_id"]) == before + + # 补齐入口:真的跑一次,数来自当前版本(170.5 + 1000) + done = await client.post(f"/api/ledger/drafts/{body['id']}/trial", + json={"inputs": {"start": "2026-09-01", "end": "2026-09-08"}}) + assert done.status_code == 200, done.text + trial = done.json() + assert trial["status"] == "succeeded", trial.get("error") + assert trial["version"] == 2 and trial["error"] == "" + assert float(trial["metrics"][0]["value"]) == 1170.5 + assert [query["node_id"] for query in trial["queries"]] == ["fetch"] + + # 草稿详情和试跑都认这一版:图里的入口字段和 SQL 就是现在这一版,试跑不算 stale + made = (await client.get(f"/api/ledger/drafts/{body['id']}")).json() + assert [field["name"] for field in made["entry_fields"]] == ["start", "end"] + assert "1000" in made["sql"] and made["version"] == 2 + assert made["trial"]["status"] == "succeeded" + assert (await client.get(f"/api/ledger/drafts/{body['id']}/trial")).json()["status"] == "succeeded" + finally: + await run_manager.shutdown() + + +async def test_the_trial_of_a_taken_over_draft_reports_a_derivation_problem_without_running(client, tmp_path): + """图本身派生不出来(入口字段没声明、模板引用了它)时照实说,也不发起运行。""" + await run_manager.setup() + try: + await S.fresh_source(tmp_path / "shop.db") + sql = S.TEMPLATE.replace("{{ input.end }}", "{{ input.undefined_param }}") + body = await attached_draft(graph=graph(sql), payload={"entry_fields": [], "sql": "SELECT 1 AS gmv"}) + before = await runs_of(body["workflow_id"]) + res = await client.post(f"/api/ledger/drafts/{body['id']}/trial", + json={"inputs": {"start": "2026-09-01", "end": "2026-09-08"}}) + assert res.status_code == 200, res.text + assert res.json()["status"] == "failed" and "undefined_param" in res.json()["error"] + assert await runs_of(body["workflow_id"]) == before + finally: + await run_manager.shutdown() + + +async def test_a_parameter_with_no_value_stops_before_any_sql(client, tmp_path): + """可选、但没声明缺省值的入口被 SQL 用着:这次没给就是缺参数(needs_input),一条 SQL 都不发。 + + 和 K01 的参数完整性同一套:声明了 `""` 缺省值的(「空值不过滤」那种写法)照缺省值渲染,不算缺参。 + """ + await run_manager.setup() + try: + await S.fresh_source(tmp_path / "shop.db") + fields = [{"name": "start", "required": True}, {"name": "end", "required": True}, + {"name": "region", "type": "string", "description": "区域(可选;没声明缺省值)"}] + sql = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}' " + "AND ('{{ input.region }}' = '' OR region = '{{ input.region }}')") + body = await attached_draft(graph=graph(sql, fields=fields), payload={"sql": "SELECT 1 AS gmv"}) + before = await runs_of(body["workflow_id"]) + res = await client.post(f"/api/ledger/drafts/{body['id']}/trial", + json={"inputs": {"start": "2026-09-01", "end": "2026-09-08"}}) + assert res.status_code == 200, res.text + assert res.json()["status"] == "needs_input" and "region" in res.json()["error"] + assert await runs_of(body["workflow_id"]) == before + + # 声明 `""` 缺省值的可选入口(空值不过滤):不给也能跑,SQL 照缺省值渲染 + open_graph = graph(sql, fields=[{**fields[0]}, {**fields[1]}, {**fields[2], "default": ""}]) + async with SessionLocal() as session: + workflow = await session.get(Workflow, body["workflow_id"]) + workflow.graph, workflow.version = open_graph, 2 + session.add(WorkflowVersion(workflow_id=body["workflow_id"], version=2, graph=open_graph, + graph_hash=graph_hash(open_graph))) + await session.commit() + done = await client.post(f"/api/ledger/drafts/{body['id']}/trial", + json={"inputs": {"start": "2026-09-01", "end": "2026-09-08"}}) + assert done.status_code == 200, done.text + assert done.json()["status"] == "succeeded" and float(done.json()["metrics"][0]["value"]) == 170.5 + finally: + await run_manager.shutdown() + + +async def test_a_really_attached_draft_runs_its_trial_from_the_current_graph(client, monkeypatch, tmp_path): + """真走一次 docattach:接上来的草稿再试跑,读的是接上之后图上又改过的那一版,payload 的旧字段不算数。 + + 和上面那条一样的几条断言,但工作流是 `docattach.attach` 真建出来的(问数据 → 比对 → 接上),不是手搭的形状。 + """ + from app.ledger import docattach + from tests.test_caliber_docdraft_attach import ask, document, payload as attached + + await run_manager.setup() + try: + await S.fresh_source(tmp_path / "shop.db") + run = await ask(monkeypatch) + doc_id, chunk_id = await document() + draft_id = uuid.uuid4().hex[:32] + definition = attached(doc_id, chunk_id) + async with SessionLocal() as session: + session.add(CaliberDraft(id=draft_id, title="周销售口径", status="ready", payload=definition)) + await session.commit() + async with SessionLocal() as session: + made = await docattach.attach(session, payload=definition, name="周销售口径", run_id=run.id, + draft_id=draft_id) + workflow_id = made["workflow_id"] + + # 接上来之后画布又改过:图上加了入口字段 region,取数按它筛(这一版才是当前版) + async with SessionLocal() as session: + workflow = await session.get(Workflow, workflow_id) + current = copy.deepcopy(workflow.graph) + draft = await session.get(CaliberDraft, draft_id) + # payload 停在接上那一刻的旧快照:一个旧字段名、版本 1 + draft.payload = {**draft.payload, "workflow_id": workflow_id, "version": 1, + "entry_fields": [{"name": "store", "description": "旧快照里的字段"}]} + draft.workflow_id, draft.status = workflow_id, "attached" + await session.commit() + region_sql = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' " + "AND region = '{{ input.region }}'") + for node in current["nodes"]: + if node["type"] == "input": + node["data"]["config"]["fields"] = [{"name": "region", "type": "string", "required": True, + "description": "地区"}] + elif node["type"] == "tool": + node["data"]["config"]["args"]["sql"] = region_sql + saved = await client.patch(f"/api/workflows/{workflow_id}", json={"graph": current, "expected_revision": 1}) + assert saved.status_code == 200 and saved.json()["version"] == 2, saved.text + + # 入口字段按图里的:payload 里的旧字段名是不认识的字段 + stale_field = await client.post(f"/api/ledger/drafts/{draft_id}/trial", + json={"inputs": {"store": "east"}}) + assert stale_field.status_code == 422, stale_field.text + assert "不认识的入口字段" in stale_field.text and "store" in stale_field.text + + before = await runs_of(workflow_id) + missing = await client.post(f"/api/ledger/drafts/{draft_id}/trial", json={"inputs": {}}) + assert missing.status_code == 422 and "region" in missing.text # 必填没给:不发 SQL + assert await runs_of(workflow_id) == before + + done = await client.post(f"/api/ledger/drafts/{draft_id}/trial", json={"inputs": {"region": "east"}}) + assert done.status_code == 200, done.text + assert done.json()["status"] == "succeeded", done.json().get("error") + assert done.json()["version"] == 2 and float(done.json()["metrics"][0]["value"]) == 156.5 + assert (await client.get(f"/api/ledger/drafts/{draft_id}")).json()["trial"]["status"] == "succeeded" + finally: + await run_manager.shutdown() + + +# ========================================================================== +# 来源基线:老草稿如实说 unknown,已记的快照照原样 +# ========================================================================== + +async def test_an_old_draft_says_its_source_baseline_is_unknown(client): + """没有可还原快照的老草稿:草稿详情给 baseline_unknown,也不凭空补一条快照。""" + draft_id = uuid.uuid4().hex[:32] + async with SessionLocal() as session: + session.add(CaliberDraft(id=draft_id, title="老草稿", status="path_pending", + payload={"metrics": [{"id": "m1", "name": "旧指标"}], "sql": "SELECT 1 AS n", + "version": 1, "workflow_id": None})) + await session.commit() + try: + body = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + assert body["metrics"][0]["name"] == "旧指标" + assert "source_snapshot" not in body + assert body["source_baseline"]["status"] == "baseline_unknown" + assert "无法还原" in body["source_baseline"]["reason"] and "artifact_id" not in body["source_baseline"] + finally: + async with SessionLocal() as session: + row = await session.get(CaliberDraft, draft_id) + if row is not None: + await session.delete(row) + await session.commit() + + +async def test_a_baseline_is_recomputed_from_the_artifact_and_never_read_from_the_payload(client): + """反例(复核):payload 里写着 known、工件却不在(或被人改过)时,读草稿要照实说 baseline_unknown。 + + 来源基线是**读工件现算**的:工件读得回来才 known(readable=true,段落以工件为准),读不回来就是 unknown + (readable=false,带上那个工件 id 和原因),不照抄 payload 里存过的状态,也不抛出去把页面弄崩。""" + from app.core.artifact_store import put_json + from app.core.config import settings + from app.ledger import docdraft + + draft_id = uuid.uuid4().hex[:32] + snapshot = docdraft.source_snapshot(documents=[{"document_id": "d1", "content": "退款率按已支付订单统计"}], + chunks={"d1-0": {"document_id": "d1", "ordinal": 0, + "content": "退款率按已支付订单统计"}}) + artifact_id = await put_json(snapshot, kind=docdraft.SNAPSHOT_KIND) + ref = docdraft.snapshot_ref(artifact_id, snapshot) + # payload 里存着的那份状态是「当时算出来的」,工件真伪由读的时候现验 + stale = {"status": "known", "artifact_id": artifact_id, "version": 1, "chunk_ids": ["d1-0"], "note": "起草时写的"} + async with SessionLocal() as session: + session.add(CaliberDraft(id=draft_id, title="有基线的草稿", status="ready", + payload={"metrics": [{"id": "m1", "name": "退款率"}], + "source_snapshot": copy.deepcopy(ref), + "source_baseline": copy.deepcopy(stale)})) + await session.commit() + path = settings.data_dir / "artifacts" / artifact_id[:2] / f"{artifact_id}.json" + original = path.read_bytes() + try: + body = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + assert body["source_snapshot"] == ref + # 工件读得回来:known(readable=true),段落以工件为准,不照抄 payload 里那份(note 不再出现) + assert body["source_baseline"] == {"status": "known", "readable": True, "artifact_id": artifact_id, + "version": docdraft.SNAPSHOT_VERSION, "chunk_ids": ["d1-0"]} + assert docdraft.source_baseline(body) == body["source_baseline"] + + path.write_text('{"kind": "caliber_source_snapshot", "tampered": true}', encoding="utf-8") + tampered = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + assert tampered["source_baseline"]["status"] == "baseline_unknown" + assert tampered["source_baseline"]["readable"] is False + assert tampered["source_baseline"]["artifact_id"] == artifact_id # 说得出是哪一个工件读不回来 + assert "读不回来" in tampered["source_baseline"]["reason"] + assert (await client.get(f"/api/ledger/drafts/{draft_id}/trial")).status_code in (200, 404) + assert (await client.get(f"/api/ledger/drafts/{draft_id}/validations")).status_code == 200 + + path.unlink() + gone = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + assert gone["source_baseline"]["status"] == "baseline_unknown" + assert gone["source_baseline"]["readable"] is False + finally: + path.write_bytes(original) + async with SessionLocal() as session: + row = await session.get(CaliberDraft, draft_id) + if row is not None: + await session.delete(row) + await session.commit() + assert (await client.get(f"/api/ledger/drafts/{draft_id}")).status_code == 404 diff --git a/backend/tests/test_caliber_entry_field_merge.py b/backend/tests/test_caliber_entry_field_merge.py new file mode 100644 index 00000000..6e2d0cac --- /dev/null +++ b/backend/tests/test_caliber_entry_field_merge.py @@ -0,0 +1,248 @@ +"""草稿入口字段的类型合并(R02):同一个字段在各组里声明成不同类型时,合并结果与各组先后无关。 + +**反例。** 两组把同一个入口字段一个声明成 integer、一个声明成 number:修复前合并出来的类型跟着**第一组**走 +(`"string" if "string" in (old, new) else old`),第一组说整数,后面那组填小数就在入口表单被拒收——同一份草稿,只是 +两组的先后不同,出的图和试跑结果就不一样。 + +**真实入口。** 各组草案由 draftplan.merge_entry_fields / _merge_fields 合并(起草后台 authoring 用它写 payload 的 +entry_fields,build_graph 用它写 start 节点的 fields),合并出来的类型进 apps.forms.input_schema,试跑、组合式问数、 +出具都按它收值(api/ledger.trial_caliber、草稿试跑、ledger/compose、ledger/issue 里的 validate_form)。所以这条规则 +不是辅助函数内部的事:改错了值就进不来,改松了不该收的值就进来了。 + +规则(draftplan._merged_type):数 + 整数并成数(数能填小数,收得下整数那一组的值,反过来 3.5 会被「整数」拒收); +文字跟谁都能并;是或否和数(整数)不能互相表示,退回文字;认不出的写法(date、int、写空)按文字算。合并结果永远 +落在 ENTRY_TYPES 里,两边对调结果一样。 + +覆盖:正序 / 逆序 / 三条以上混合顺序 / 非法类型 / 建图 / 入口表单 / 真引擎试跑。 +""" +from __future__ import annotations + +import itertools +import json +import sqlite3 + +import pytest +from sqlalchemy import select + +from app.api import ledger as api_ledger +from app.db.base import SessionLocal +from app.db.models import DataSource, Run +from app.engine.runner import run_manager +from app.engine.schema import GraphSpec, validate_graph +from app.ledger import draftplan +from tests.test_ledger_docdraft_api import ( + REAL_RUN_TRIAL, client, datasource, documents, extract, fake_model, plan_reply, +) + +#: 这个文件里每一组都声明的同一个入口字段:要合并的就是它的类型 +FIELD = "threshold" +#: 能认的四种类型(draftplan.ENTRY_TYPES),加上几种认不出的写法(大小写、多空格也不放宽:入口这一层只认原样的四个词) +KINDS = (*draftplan.ENTRY_TYPES, "date", "int", None, "", "INTEGER ") + + +def field(kind, *, required: bool = True, **extra) -> dict: + return {"name": FIELD, "type": kind, "required": required, **extra} + + +def block(kind, *, sql: str = "SELECT 1 AS gmv FROM orders", metrics: list[dict] | None = None) -> dict: + """一组草案:一条取数 SQL、一份入口字段声明、几个指标。""" + return {"sql": sql, "entry_fields": [field(kind)], "metrics": list(metrics or [])} + + +def merged_type(*kinds) -> str: + """按各组先后合并同一个字段,返回合并后的类型(也顺带确认每组都只声明这一个字段)。""" + fields, _ = draftplan.merge_entry_fields([block(kind) for kind in kinds]) + assert [f["name"] for f in fields] == [FIELD] + return fields[0]["type"] + + +def start_fields(graph: dict) -> list[dict]: + return next(node for node in graph["nodes"] if node["id"] == "start")["data"]["config"]["fields"] + + +# ========================================================================== +# 合并规则:正序、逆序、混合顺序、非法类型 +# ========================================================================== + +def test_integer_and_number_merge_to_number_whichever_group_comes_first(): + """R02 的最小反例:两组一个整数、一个数,两个先后都并成数(修复前跟着第一组走)。""" + assert merged_type("integer", "number") == "number" + assert merged_type("number", "integer") == "number" + fields, notes = draftplan.merge_entry_fields([block("integer"), block("number")]) + assert fields[0]["type"] == "number" + assert any(FIELD in note and "类型" in note and "number" in note for note in notes) + + +@pytest.mark.parametrize("left,right", list(itertools.permutations(KINDS, 2))) +def test_merging_a_pair_does_not_depend_on_which_group_comes_first(left, right): + """任意两种声明(含认不出的写法)对调先后,合并出来的类型一样,而且落在 ENTRY_TYPES 里。""" + forward, backward = merged_type(left, right), merged_type(right, left) + assert forward == backward + assert forward in draftplan.ENTRY_TYPES + + +@pytest.mark.parametrize("kinds", list(itertools.permutations(["integer", "number", "string"])) + + list(itertools.permutations(["integer", "number", "boolean"])) + + list(itertools.permutations(["integer", "number", "boolean", "string"]))) +def test_three_or_more_groups_merge_the_same_in_any_order(kinds): + """三条以上混合顺序:合并结果只跟这几种声明有关,跟它们谁先谁后无关。""" + assert merged_type(*kinds) == merged_type(*reversed(kinds)) + + +def test_a_multiset_of_declarations_always_merges_to_one_result(): + """穷举(含认不出的写法):同一组声明的任意先后只并出一个类型,重复声明、三条以上也一样。""" + kinds = [*draftplan.ENTRY_TYPES, "date", "int", "", None] + for size in (2, 3, 4): + for declared in itertools.product(kinds, repeat=size): + got = {merged_type(*order) for order in set(itertools.permutations(declared))} + assert len(got) == 1, (declared, got) + + +@pytest.mark.parametrize("kinds,expect", [ + (("integer", "number"), "number"), + (("number", "integer", "number"), "number"), + (("string", "number"), "string"), + (("string", "integer"), "string"), + (("boolean", "integer"), "string"), + (("boolean", "number"), "string"), + (("integer", "number", "boolean"), "string"), +]) +def test_the_merged_type_is_the_wider_one(kinds, expect): + """并出来的类型:数收得下整数(也收得下小数),文字跟谁都能并,是或否与数不能互相表示就退回文字。""" + assert merged_type(*kinds) == expect + + +@pytest.mark.parametrize("kind", ["date", "int", "float", "INTEGER ", "", None, 3, ["number"]]) +def test_declarations_we_do_not_recognise_count_as_text(kind): + """认不出的声明按文字算(和 _entry_fields、apps.forms.input_schema 一个认法):跟谁并都并成文字,也不照抄进图里。""" + assert merged_type(kind) == "string" + assert merged_type(kind, "integer") == "string" + assert merged_type("integer", kind) == "string" + assert merged_type(kind, kind) == "string" + + +def test_an_unrecognised_declaration_is_normalised_even_with_one_group(): + """认不出的声明按文字算(和 _entry_fields 同一份判断):只有一组时也规范化,不把 date 之类的原样写进图。""" + fields, notes = draftplan.merge_entry_fields([block("date")]) + assert fields[0]["type"] == "string" and notes == [] + fields, notes = draftplan.merge_entry_fields([block("number")]) + assert fields[0]["type"] == "number" and notes == [] + + +# ========================================================================== +# 建图:start 节点的 fields 与组序无关 +# ========================================================================== + +def test_build_graph_start_fields_do_not_depend_on_group_order(): + """建图走的是同一条合并规则:start 节点的 fields(图里的入口契约)与 payload 里的入口字段一致,两序相同。""" + metric = {"id": "m1", "name": "销售额", "expression": "cell(nodes.fetch, 0, 'gmv')"} + first = block("integer", metrics=[metric]) + second = block("number", metrics=[{**metric, "id": "m2", "name": "订单数", + "expression": "cell(nodes.fetch, 0, 'cnt')"}]) + forward = draftplan.build_graph([first, second], name="金额下限", datasource="shop") + backward = draftplan.build_graph([second, first], name="金额下限", datasource="shop") + assert start_fields(forward) == start_fields(backward) == \ + draftplan.merge_entry_fields([first, second])[0] + assert start_fields(forward)[0]["type"] == "number" + for graph in (forward, backward): + result = validate_graph(GraphSpec.model_validate(graph)) + assert result.ok, [issue.message for issue in result.issues if issue.level == "error"] + + +def test_the_entry_form_takes_whole_and_fractional_values_after_merging(): + """合并出来的类型就是入口表单收值用的那一份:并成数之后 3 和 3.5 都收得下(并成整数时 3.5 会被拒)。""" + from app.apps.forms import input_schema, validate_form + + values = {FIELD: 3.5} + for kinds in (("integer", "number"), ("number", "integer")): + fields, _ = draftplan.merge_entry_fields([block(kind) for kind in kinds]) + schema = input_schema(fields) + assert schema["properties"][FIELD]["type"] == "number" + assert validate_form(schema, values) == [] + assert validate_form(schema, {FIELD: 3}) == [] + # 对照:只声明成整数时小数确实收不下(修复前 integer 在前的顺序就是并成这个,试跑会 422) + integer_schema = input_schema(draftplan.merge_entry_fields([block("integer")])[0]) + assert validate_form(integer_schema, values), "整数类型不收小数" + + +# ========================================================================== +# 真引擎:正序、逆序各跑一次,小数进到 SQL 里 +# ========================================================================== + +async def _orders_draft(client, documents, datasource, monkeypatch, tmp_path, *, first_type: str): + """从文档起草一份两组的草稿:同一个入口字段一组声明成 first_type、另一组声明成另一种,试跑走真引擎。 + + 门店库换成临时文件(orders 五行,>= 2.5 的是 5、2.5、3 三行);两条 SQL 都用裸写的 `amount >= {{ input.threshold }}` + (裸写位置只收数)。返回(草稿 id, 草稿详情)。 + """ + doc = await documents("dd-merge-" + first_type) + source_id = await datasource() + path = tmp_path / f"merge-{first_type}.db" + with sqlite3.connect(path) as db: + db.execute("CREATE TABLE orders (status TEXT, amount REAL)") + db.executemany("INSERT INTO orders VALUES (?, ?)", + [("paid", 5.0), ("paid", 2.5), ("paid", 2.0), ("paid", 3.0), ("refunded", 100.0)]) + db.commit() + async with SessionLocal() as session: + source = await session.get(DataSource, source_id) + source.database, source.readonly, source.enabled = str(path), True, True + await session.commit() + + gmv, count = json.loads(plan_reply(f"{doc}-2")), json.loads(plan_reply(f"{doc}-2")) + other = "number" if first_type == "integer" else "integer" + gmv["entry_fields"] = [field(first_type, required=True, description="金额下限")] + gmv["sql"] = "SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' AND amount >= {{ input.threshold }}" + gmv["metrics"] = [{**gmv["metrics"][0], "id": "m1", "name": "金额下限以上销售额", + "expression": "cell(nodes.fetch, 0, 'gmv')"}] + gmv["uncovered"] = ["金额下限以上订单数"] + count["entry_fields"] = [field(other, required=True, description="金额下限")] + count["sql"] = "SELECT COUNT(*) AS cnt FROM orders WHERE status = 'paid' AND amount >= {{ input.threshold }}" + count["metrics"] = [{**count["metrics"][0], "id": "m1", "name": "金额下限以上订单数", + "expression": "cell(nodes.fetch, 0, 'cnt')"}] + count["uncovered"] = [] + fake_model(monkeypatch, json.dumps(gmv, ensure_ascii=False), json.dumps(count, ensure_ascii=False)) + monkeypatch.setattr(api_ledger, "_run_trial", REAL_RUN_TRIAL) + + created = await extract(client, doc, source_id) + made = (await client.get("/api/ledger/drafts/" + created["draft_id"])).json() + assert made["status"] in ("ready", "questions_open"), made.get("error") + assert made["blocks"] == 2, made.get("blocks") + return created["draft_id"], made + + +async def _cleanup_run(run_id: str) -> None: + async with SessionLocal() as session: + row = await session.get(Run, run_id) + if row is not None: + await session.delete(row) + await session.commit() + + +@pytest.mark.parametrize("first_type", ["integer", "number"]) +async def test_a_fractional_entry_value_reaches_sql_whichever_group_comes_first( + client, documents, datasource, monkeypatch, tmp_path, first_type): + """完整请求链:文档起草两组 → 合并入口类型 → 草稿图 → 试跑入口校验 → 真引擎跑一次。 + + 两组的先后不同,草稿里的入口类型、试跑收到的值(2.5 没被截成 2)和两条 SQL 的结果都该一样。 + """ + await run_manager.setup() + run_id = "" + try: + draft_id, made = await _orders_draft(client, documents, datasource, monkeypatch, tmp_path, + first_type=first_type) + fields = {f["name"]: f for f in made["entry_fields"]} + assert fields[FIELD]["type"] == "number", made["entry_fields"] + assert any(FIELD in note and "类型" in note for note in made["entry_notes"]) + + trial = (await client.post(f"/api/ledger/drafts/{draft_id}/trial", + json={"inputs": {FIELD: 2.5}})).json() + run_id = str(trial.get("run_id") or "") + assert trial["status"] == "succeeded", trial.get("error") + assert {m["id"]: m["value"] for m in trial["metrics"]} == {"m1": 10.5, "m2": 3}, trial["metrics"] + # 两条取数各自把 2.5 渲染进 SQL:值被当成整数截断的话这里会是 12.5 和 4 + rows = {query["node_id"]: query["rows"] for query in trial["queries"]} + assert sorted(rows) == ["fetch_1", "fetch_2"] + assert sorted(row[0] for got in rows.values() for row in got) == [3, 10.5] + finally: + await run_manager.shutdown() + await _cleanup_run(run_id) diff --git a/backend/tests/test_caliber_field_baseline.py b/backend/tests/test_caliber_field_baseline.py new file mode 100644 index 00000000..1991001b --- /dev/null +++ b/backend/tests/test_caliber_field_baseline.py @@ -0,0 +1,176 @@ +"""K05 的字段基线 B:首次接受导入时把**被接受的导入值**按 metric_id + field_path 存成不可变工件。 + +这份文件盯住任务书 4.7 的三件硬要求: + +1. **首次接受导入就是 B 的那一次。** 导入成功规范化、落进初始草稿图的那一刻,被接受的字段值(含引用原文这类不可变 + 引用)按 metric_id + field_path 存下来,逐格带值哈希,并连着来源快照与 accepted_revision。读得回来——不是只 + 存一个哈希(哈希还原不了 B)。 +2. **人工改 L 不动 B。** 字段操作(K03)改的是当前内容;B 还是当初被接受的那一份,一个字不动(也不因为改过了就 + 把当前值写回基线)。 +3. **旧资产 baseline_unknown。** 保存基线之前建的草稿没有引用:如实标 unknown,不拿它现在的内容倒填历史基线。 + +模型一律注入假模型、试跑换成假的;这里不连真实业务库。 +""" +from __future__ import annotations + +import copy +import uuid + +import pytest +from sqlalchemy import delete, select + +from app.db.base import SessionLocal +from app.db.models import CaliberDraft +from app.ledger import fieldbaseline +from tests.test_ledger_docdraft_api import ( # noqa: F401 - fixture 和起草用例共用 + client, datasource, documents, extract, fake_model, fake_trial, plan_reply, +) + + +async def accepted_draft(client, documents, datasource, monkeypatch) -> dict: + """走一次真实起草(假模型 + 假试跑),返回草稿详情。""" + doc = await documents("baseline-" + uuid.uuid4().hex[:8]) + source_id = await datasource() + fake_model(monkeypatch, plan_reply(f"{doc}-2")) + body = await extract(client, doc, source_id) + return (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json() + + +@pytest.fixture(autouse=True) +def _fake_trial(fake_trial): + """本模块的草稿都走接口起草:试跑必须换成假的,不然会去打夹具里不存在的库。 + + (fake_trial 是从别的模块 import 进来的普通夹具,它自带的 autouse 在本模块不生效;这里替本模块的每个用例把它拉起来。)""" + return fake_trial + + +async def test_the_first_accepted_import_is_stored_as_a_readable_value_level_baseline( + client, documents, datasource, monkeypatch): + """接受导入那一刻存下的是**逐字段的值**:读得回来、哈希对得上、连着来源快照和接受版本。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + + baseline = made["field_baseline"] + assert baseline["status"] == "known" and baseline["accepted_revision"] == 1 + assert baseline["metric_ids"] == ["m1"] and baseline["field_count"] >= 5 + # payload 里另有一份追加式的历史(这次接受是第一条) + assert [item["artifact_id"] for item in made["field_baseline_history"]] == [baseline["artifact_id"]] + assert baseline["source_snapshot_artifact_id"] == made["source_snapshot"]["artifact_id"] + + # 按引用读回工件:内容就是当时被接受的那一份,逐格有值、有哈希(不是一串哈希) + stored = fieldbaseline.read({"artifact_id": baseline["artifact_id"]}) + assert stored["card_id"] == made["card_id"] and stored["accepted_revision"] == 1 + fields = stored["metrics"]["m1"]["fields"] + assert fields["/name"]["value"] == "已支付退款率" + assert fields["/unit"]["value"] == "%" and fields["/decimals"]["value"] == 2 + assert fields["/definition/text"]["value"] == "已支付订单里发生退款的比例" + assert fields["/synonyms"]["value"] == ["退款率"] + # 引用原文是「不可变值引用」:整条留着(哪一段、原话、span),重导入要拿它比 + citation = fields["/definition/citations"]["value"][0] + assert citation["quote"] == "只算已支付的订单" and citation["span"] == [8, 16] + assert all(cell["hash"] for cell in fields.values()) + # 同一份材料只存一份:引用里的 content_hash 就是工件 id(内容寻址) + assert baseline["content_hash"] == baseline["artifact_id"] + assert fieldbaseline.values({"artifact_id": baseline["artifact_id"]}, "m1")["/name"] == "已支付退款率" + + +async def test_editing_fields_moves_l_and_never_touches_b(client, documents, datasource, monkeypatch): + """人工按字段改(K03)只改 L:B 的引用、值、哈希一个字不动,覆盖判断跟着定义指纹走。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + before_ref = copy.deepcopy(made["field_baseline"]) + before_fields = fieldbaseline.values({"artifact_id": before_ref["artifact_id"]}) + assert made["validation"]["covers_current"] is True + + changed = await client.patch(f"/api/ledger/drafts/{made['id']}", json={ + "operations": [{"op": "set", "metric_id": "m1", "path": "/name", "value": "退款率(人工改过)"}, + {"op": "set", "metric_id": "m1", "path": "/definition/text", "value": "人工写的新说明"}], + "expected_revision": made["revision"], "request_id": "baseline-edit-1"}) + assert changed.status_code == 200, changed.text + assert changed.json()["change"]["applied"] is True + + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["metrics"][0]["name"] == "退款率(人工改过)" # L 变了 + assert after["metrics"][0]["definition"]["text"] == "人工写的新说明" + assert after["field_baseline"] == before_ref # B 的引用原样 + assert fieldbaseline.values({"artifact_id": after["field_baseline"]["artifact_id"]}) == before_fields + # B 里还是当初被接受的那一份,不是「现在长什么样」 + assert fieldbaseline.values({"artifact_id": after["field_baseline"]["artifact_id"]}, "m1")["/name"] \ + == "已支付退款率" + # 定义改了,旧验证记录不再覆盖当前版本(覆盖是读的时候按指纹现算的) + assert after["validation"]["covers_current"] is False + assert after["validation"]["verdict"] == "stale" + + +async def test_an_old_draft_reads_as_baseline_unknown_and_is_never_backfilled(client): + """没有可还原基线的老草稿:如实说 unknown,不拿它现在的内容当 B,也不因为读一次就补一份出来。""" + draft_id = "old-" + uuid.uuid4().hex[:10] + async with SessionLocal() as session: + session.add(CaliberDraft(id=draft_id, title="老草稿", status="path_pending", + payload={"metrics": [{"id": "m1", "name": "旧指标", + "definition": {"text": "老草稿里现在写的说明"}}]})) + await session.commit() + try: + detail = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + assert detail["field_baseline"]["status"] == "baseline_unknown" + assert "artifact_id" not in detail["field_baseline"] + assert "无法还原" in detail["field_baseline"]["reason"] + + listed = (await client.get(f"/api/ledger/drafts/{draft_id}/validations")).json() + assert listed["field_baseline"]["status"] == "baseline_unknown" + assert listed["records"] == [] and listed["summary"]["verdict"] == "none" + + # 再读一次也不会「补」出一份基线:草稿里现在有指标,B 仍旧是 unknown(当前值不是历史基线) + again = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + assert again["field_baseline"]["status"] == "baseline_unknown" + assert fieldbaseline.ref_of(again) is None + finally: + async with SessionLocal() as session: + row = await session.get(CaliberDraft, draft_id) + if row is not None: + await session.delete(row) + await session.commit() + + +async def test_the_baseline_is_content_addressed_and_keeps_every_acceptance(client, documents, datasource, + monkeypatch): + """同一份被接受的材料只存一份工件;每次接受追加一条引用,当前 B 是最后一条。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + ref = dict(made["field_baseline"]) + metrics = [{"id": "m1", "name": "已支付退款率", "unit": "%", "decimals": 2, + "definition": {"text": "已支付订单里发生退款的比例"}}] + again = await fieldbaseline.put_metrics(metrics=metrics, card_id=ref["card_id"], workflow_id=ref["workflow_id"], + accepted_revision=1, draft_id=made["id"]) + assert again is not None and again["artifact_id"] != ref["artifact_id"] # 字段少了,内容不同 → 另一份工件 + assert ref["artifact_id"] not in (again["artifact_id"],) + history = fieldbaseline.history({**made, fieldbaseline.HISTORY_KEY: [ref, again]}) + assert [item["artifact_id"] for item in history] == [ref["artifact_id"], again["artifact_id"]] + + +async def test_a_baseline_that_cannot_be_stored_leaves_the_draft_readable(monkeypatch, client, documents, + datasource): + """基线落库失败不把草稿判死:照实说没有基线(baseline_unknown),不假装有。""" + from app.core import artifact_store + + async def boom(*args, **kwargs): + raise OSError("工件库写不进去") + + monkeypatch.setattr(artifact_store, "put_json", boom) + broken = await accepted_draft(client, documents, datasource, monkeypatch) + assert broken["status"] == "ready" # 草稿照出 + assert broken["field_baseline"]["status"] == "baseline_unknown" + assert "无法还原" in broken["field_baseline"]["reason"] + + +@pytest.fixture(autouse=True) +async def _cleanup_records(): + """本模块造的草稿由 documents 夹具统一清掉;这里兜一下记录表,避免留下跨用例的残行。""" + yield + from app.db.models import CaliberReviewDecision, CaliberValidationRecord + + async with SessionLocal() as session: + drafts = list((await session.execute(select(CaliberDraft.id))).scalars()) + if drafts: + await session.execute(delete(CaliberValidationRecord).where( + CaliberValidationRecord.draft_id.in_(drafts))) + await session.execute(delete(CaliberReviewDecision).where( + CaliberReviewDecision.draft_id.in_(drafts))) + await session.commit() diff --git a/backend/tests/test_caliber_field_changes.py b/backend/tests/test_caliber_field_changes.py new file mode 100644 index 00000000..169522c0 --- /dev/null +++ b/backend/tests/test_caliber_field_changes.py @@ -0,0 +1,673 @@ +"""K03 字段变更闭环:按稳定 metric_id + 字段路径改一处,整批原子、图是原图的深拷贝、回执不吹验证。 + +- 打补丁打在**原图的深拷贝**上:没提到的字段(definition 的 citations/owner、contract、扩展字段)、别的指标、 + 别人加的图级扩展字段和其他节点的配置都原样保留(E02); +- 白名单:真有的业务字段和 definition 的展示字段能改,id / citations / 负责人 / 生效日期 / 指标类型 / 契约 / + 任意路径 / 按数组位置定位一律拒,且各自有一句具体的话(不是笼统的「不认识」); +- 省略、set 空串(数组是 [])、set null、remove 四种写法语义不同;数组字段整份设置; +- 一批要么全成、要么全不成:一条不合规就一条都不落地,也不新增版本;整批最后没改动内容(先设后删)同样不落版本; +- 回执带变更分类、影响指标、定义指纹前后值、失效说明和绑定状态——没有绑定已对齐、也没有验证通过这种话; +- 同一语义变化经画布(整图保存)和经 operations 得到同一张执行图,旧试跑都判过期(E08); +- K02 的规矩一条不少:要带 expected_revision、旧写 409 stale_revision、同一 request_id 幂等(指纹包含 operations)、 + 同键不同内容 409 idempotency_conflict、并发同键只落一版;整份换指标那条老路照旧(回执不带 change 段)。 + +模型一律注入假模型(test_ledger_docdraft_api.fake_model),试跑换成写一行 succeeded 的运行(fake_trial),不发真实请求。 +""" +from __future__ import annotations + +import asyncio +import copy +import json +import uuid + +import pytest +from sqlalchemy import select + +from app.api import ledger as api_ledger +from app.core.artifact_store import execution_hash, graph_hash +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, CaliberWriteRequest, Workflow, WorkflowVersion +from app.ledger import changes +from app.ledger.repository import CaliberGone, GraphBackedCaliberRepository, MetricGone +from tests.test_caliber_write_guard import ( # noqa: F401 - 这几个 fixture / 助手和 K02 的用例共用 + _graph_of, _versions, cfg, client, datasource, documents, fake_trial, ready_draft, +) + + +def patch_url(draft_id: str) -> str: + return f"/api/ledger/drafts/{draft_id}" + + +def ops_set(metric_id: str, path: str, value) -> dict: + return {"op": "set", "metric_id": metric_id, "path": path, "value": value} + + +def ops_remove(metric_id: str, path: str) -> dict: + return {"op": "remove", "metric_id": metric_id, "path": path} + + +async def change(client, body: dict, operations: list[dict], *, request_id: str | None = None, + expected_revision: int | None = None, **extra): + """按字段改一次(默认带上读草稿时给的基准版本)。""" + payload = {"operations": operations, + "expected_revision": body["revision"] if expected_revision is None else expected_revision, **extra} + if request_id is not None: + payload["request_id"] = request_id + return await client.patch(patch_url(body["id"]), json=payload) + + +def metric_of(graph: dict, metric_id: str = "m1", card: str = "card") -> dict: + metrics = cfg(graph, card)["metrics"] + return next(metric for metric in metrics if metric["id"] == metric_id) + + +async def bare_draft(client, metrics: list[dict]) -> dict: + """一份手建的已接管草稿(docattach 那种:tags 有 doc_draft、origin 里没有 kind),图上只有一张口径卡。 + + 起草出来的指标总是带整份 definition,画布上却什么形状都可能:边角形状(没有 definition、definition 是 + null、被人写成字符串)走它来试。 + """ + workflow_id = f"wf-{uuid.uuid4().hex[:12]}" + draft_id = uuid.uuid4().hex[:32] + graph = {"nodes": [{"id": "card", "type": "metrics", "position": {"x": 0, "y": 0}, + "data": {"label": "口径卡", "config": {"metrics": copy.deepcopy(metrics)}}}], "edges": []} + async with SessionLocal() as session: + session.add(Workflow(id=workflow_id, name=f"{OWN_PREFIX}手建 {uuid.uuid4().hex[:6]}", status="draft", + graph=graph, version=1, tags=["doc_draft"], + origin={"run_id": "run-1", "sources": [{"run_id": "run-1"}]})) + session.add(WorkflowVersion(workflow_id=workflow_id, version=1, graph=graph, graph_hash=graph_hash(graph))) + await session.flush() # 草稿的外键指着工作流:先落工作流那一行 + session.add(CaliberDraft(id=draft_id, title="手建口径", status="ready", workflow_id=workflow_id, + payload={"metrics": copy.deepcopy(metrics), "version": 1, + "workflow_id": workflow_id})) + await session.commit() + return {"id": draft_id, "workflow_id": workflow_id, "revision": 1, "card_id": "card"} + + +#: 这个文件自己建的工作流(连同版本、幂等记录、草稿)跑完删掉,不给后面的用例留行 +OWN_PREFIX = "K03 " + + +@pytest.fixture(autouse=True) +async def cleanup_own_rows(): + yield + async with SessionLocal() as session: + workflow_ids = list((await session.execute( + select(Workflow.id).where(Workflow.name.like(f"{OWN_PREFIX}%")))).scalars()) + if workflow_ids: + for model in (CaliberWriteRequest, WorkflowVersion, CaliberDraft): + for row in (await session.execute( + select(model).where(model.workflow_id.in_(workflow_ids)))).scalars(): + await session.delete(row) + for workflow in (await session.execute( + select(Workflow).where(Workflow.id.in_(workflow_ids)))).scalars(): + await session.delete(workflow) + await session.commit() + + +# ========================================================================== +# 原图上的字段补丁:改一处,别的都留着 +# ========================================================================== + +async def test_a_field_change_lands_on_the_graph_and_leaves_everything_else_alone( + client, documents, datasource, monkeypatch, fake_trial): + """改时间字段不动 citations / contract / 口径说明 / 扩展字段,也不动其他节点和其他指标(K03 的反例)。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + wid = body["workflow_id"] + # 图上先有别人加的扩展字段和自定义指标键(前端不认识的那些),还有第二条指标和第二条边 + graph = await _graph_of(wid) + graph["extensions"] = {"unknown": True} + card_metrics = cfg(graph, "card")["metrics"] + card_metrics[0]["x_custom"] = {"keep": [1, 2]} + card_metrics.append({"id": "m2", "name": "订单数", "expression": "cell(nodes.fetch, 0, 'orders')", + "contract": {"shape": "scalar"}}) + saved = await client.patch(f"/api/workflows/{wid}", json={"graph": graph, "expected_revision": body["revision"]}) + assert saved.status_code == 200, saved.text + before = await _graph_of(wid) + before_m1 = copy.deepcopy(metric_of(before)) + + res = await change(client, {**body, "revision": saved.json()["version"]}, + [ops_set("m1", "/time_field", "paid_at"), + ops_set("m1", "/definition/exclusions", ["全额退款"]), + ops_set("m1", "/grain", "order")]) + assert res.status_code == 200, res.text + made = res.json() + assert made["version"] == saved.json()["version"] + 1 + assert await _versions(wid) == [1, 2, 3] + + after = await _graph_of(wid) + changed = metric_of(after) + assert changed["time_field"] == "paid_at" and changed["grain"] == "order" + assert changed["definition"]["exclusions"] == ["全额退款"] + # 没碰的:口径说明、负责人、引用原文、取值契约、表达式、小数位、自定义键原样 + assert changed["definition"]["text"] == before_m1["definition"]["text"] + assert changed["definition"]["owner"] == before_m1["definition"]["owner"] + assert changed["definition"]["citations"] == before_m1["definition"]["citations"] + assert changed["contract"] == before_m1["contract"] + assert changed["expression"] == before_m1["expression"] + assert changed["decimals"] == before_m1["decimals"] + assert changed["x_custom"] == {"keep": [1, 2]} + # 别的指标、别的节点、图级扩展字段都没动 + assert metric_of(after, "m2") == metric_of(before, "m2") + for node_id in ("start", "fetch", "write", "out"): + assert cfg(after, node_id) == cfg(before, node_id) + assert after["extensions"] == {"unknown": True} and after["edges"] == before["edges"] + + # 草稿页从图读:新定义立刻可见,旧试跑按执行指纹判过期 + view = (await client.get(patch_url(body["id"]))).json() + assert view["metrics"][0]["time_field"] == "paid_at" + assert view["trial"]["status"] == "stale" + + # 回执:变更分类、影响指标、定义指纹前后值、失效说明、绑定状态(没声明业务字段的旧资产:unbound,不装对齐) + block = made["change"] + assert block["applied"] is True and block["classification"] == "definition" + assert block["metrics"] == ["m1"] and block["card"] == "card" and block["revision"] == made["version"] + assert [op["path"] for op in block["operations"]] == ["/time_field", "/definition/exclusions", "/grain"] + assert block["definition_hash"]["changed"] is True + assert block["definition_hash"]["before"] != block["definition_hash"]["after"] + assert block["validation"]["invalidated"] is True and block["validation"]["scope"] == "card" + assert block["validation"]["metrics"] == ["m1"] and "重新试运行" in block["validation"]["next"] + assert block["binding"]["status"] == "unbound" and block["binding"]["checked"] is True + assert block["binding"]["synced"] is False and block["binding"]["fix"] == "none" + assert "aligned" not in json.dumps(block, ensure_ascii=False) + + +async def test_a_batch_can_touch_several_metrics(client, documents, datasource, monkeypatch, fake_trial): + """一批操作可以落在不同指标上:影响摘要按卡上的先后列出每一条动过的指标。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + second = {**copy.deepcopy(body["metrics"][0]), "id": "m2", "name": "订单数", + "expression": "cell(nodes.fetch, 0, 'orders')"} + seeded = await client.patch(patch_url(body["id"]), + json={"metrics": [copy.deepcopy(body["metrics"][0]), second], + "expected_revision": body["revision"]}) + assert seeded.status_code == 200, seeded.text + + res = await change(client, seeded.json(), [ops_set("m2", "/unit", "笔"), ops_set("m1", "/unit", "元")]) + assert res.status_code == 200, res.text + assert res.json()["change"]["metrics"] == ["m1", "m2"] # 按卡上的先后,不按提交顺序 + after = await _graph_of(body["workflow_id"]) + assert metric_of(after, "m1")["unit"] == "元" and metric_of(after, "m2")["unit"] == "笔" + assert metric_of(after, "m2")["expression"] == second["expression"] + + +async def test_a_display_only_change_is_classified_as_display(client, documents, datasource, monkeypatch, fake_trial): + """同义词这类展示字段改完,定义指纹不动、分类是 display;页面据此能说「数字怎么算没变」。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + res = await change(client, body, [ops_set("m1", "/synonyms", ["退款率", "退单率"])]) + assert res.status_code == 200, res.text + block = res.json()["change"] + assert block["classification"] == "display" and block["definition_hash"]["changed"] is False + assert block["validation"]["invalidated"] is True # 图还是变了:旧试跑照样过期 + assert metric_of(await _graph_of(body["workflow_id"]))["synonyms"] == ["退款率", "退单率"] + # 定义类字段(时间字段)改完就是 definition + again = await change(client, res.json(), [ops_set("m1", "/time_field", "paid_at")]) + assert again.json()["change"]["classification"] == "definition" + + +async def test_untouched_metrics_and_cards_stay_untouched(client, documents, datasource, monkeypatch, fake_trial): + """同一张卡上的别的指标、以及图上另一张可写的卡:没点名就一个字段不动。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + wid = body["workflow_id"] + graph = await _graph_of(wid) + metrics = cfg(graph, "card")["metrics"] + cfg(graph, "card")["metrics"] = [*metrics, {**copy.deepcopy(metrics[0]), "id": "m2", "name": "另一个指标"}] + graph["nodes"].append({"id": "card_2", "type": "metrics", "position": {"x": 0, "y": 200}, + "data": {"label": "另一张卡", "config": {"metrics": [ + {**copy.deepcopy(metrics[0]), "id": "m9", "name": "第二张卡上的指标"}]}}}) + saved = await client.patch(f"/api/workflows/{wid}", json={"graph": graph, "expected_revision": body["revision"]}) + assert saved.status_code == 200, saved.text + before = await _graph_of(wid) + + fresh = (await client.get(patch_url(body["id"]))).json() + # 多张可写的卡、又没指明目标:拒(不做「取第一张」) + refused = await change(client, fresh, [ops_set("m1", "/unit", "元")]) + assert refused.status_code == 409 and refused.json()["code"] == "card_required", refused.text + # 指明第二张卡:改的是它,card 上一条不动 + written = await change(client, fresh, [ops_set("m9", "/unit", "元")], target={"card_id": "card_2"}) + assert written.status_code == 200, written.text + after = await _graph_of(wid) + assert metric_of(after, "m9", card="card_2")["unit"] == "元" + assert cfg(after, "card")["metrics"] == cfg(before, "card")["metrics"] # 第一张卡整份不动 + + +# ========================================================================== +# 四种写法:省略 / 空串 / null / remove +# ========================================================================== + +async def test_omit_empty_string_null_and_remove_are_four_different_things( + client, documents, datasource, monkeypatch, fake_trial): + body = await ready_draft(client, documents, datasource, monkeypatch) + before = metric_of(await _graph_of(body["workflow_id"])) + assert before["unit"] == "%" and "time_field" not in before + + # 省略:只提 unit,time_field / grain 一个字都没提,保持原样(「没有这个键」还是「没有这个键」) + first = await change(client, body, [ops_remove("m1", "/unit")]) + assert first.status_code == 200, first.text + metric = metric_of(await _graph_of(body["workflow_id"])) + assert "unit" not in metric and "time_field" not in metric and "grain" not in metric + + # set 空串:键在、值是空的——和 remove 的「没声明」不是一回事,存储上分得出来 + second = await change(client, first.json(), [ops_set("m1", "/unit", "")]) + assert second.status_code == 200, second.text + metric = metric_of(await _graph_of(body["workflow_id"])) + assert metric["unit"] == "" and "unit" in metric + + # set null:拒(「清空」有 remove、「声明为空」有 '',不替客户端猜) + null = await change(client, second.json(), [ops_set("m1", "/unit", None)]) + assert null.status_code == 422, null.text + assert null.json()["code"] == "operation_value" and "null" in null.json()["detail"] + # set 不带 value:拒 + missing = await change(client, second.json(), [{"op": "set", "metric_id": "m1", "path": "/unit"}]) + assert missing.status_code == 422 and missing.json()["code"] == "operation_value" + # remove 带 value:拒 + extra = await change(client, second.json(), [{"op": "remove", "metric_id": "m1", "path": "/unit", "value": ""}]) + assert extra.status_code == 422 and extra.json()["code"] == "operation_value" + # 三种错法都没落地:还是第二次那一份(键在、值为空串) + assert metric_of(await _graph_of(body["workflow_id"]))["unit"] == "" + assert await _versions(body["workflow_id"]) == [1, 2, 3] + + +async def test_array_fields_are_set_as_a_whole_and_never_by_position( + client, documents, datasource, monkeypatch, fake_trial): + """数组字段整份设置;想按位置改(/synonyms/0)直接拒——位置不是身份,重排会让它指到别人。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + res = await change(client, body, [ops_set("m1", "/synonyms", ["退款率"]), + ops_set("m1", "/dimensions", ["门店", "渠道"])]) + assert res.status_code == 200, res.text + metric = metric_of(await _graph_of(body["workflow_id"])) + assert metric["synonyms"] == ["退款率"] and metric["dimensions"] == ["门店", "渠道"] + + by_position = await change(client, res.json(), [ops_set("m1", "/synonyms/0", "新的同义词")]) + assert by_position.status_code == 422, by_position.text + assert by_position.json()["code"] == "operation_path" + assert "位置" in by_position.json()["detail"] + assert metric_of(await _graph_of(body["workflow_id"]))["synonyms"] == ["退款率"] + + # 值里的空串不算「声明成空」:数组元素得有内容 + empty_item = await change(client, res.json(), [ops_set("m1", "/synonyms", ["", "x"])]) + assert empty_item.status_code == 422 and empty_item.json()["code"] == "operation_value" + + +# ========================================================================== +# 非法操作:拒得具体,一个字段都不落 +# ========================================================================== + +@pytest.mark.parametrize("operation,code", [ + ({"op": "set", "metric_id": "m1", "path": "/id", "value": "m9"}, "operation_path"), + ({"op": "set", "metric_id": "m1", "path": "/definition/citations", "value": []}, "operation_path"), + ({"op": "set", "metric_id": "m1", "path": "/definition/owner", "value": "别人"}, "operation_path"), + ({"op": "set", "metric_id": "m1", "path": "/definition/effective_from", "value": "2026-01-01"}, "operation_path"), + ({"op": "set", "metric_id": "m1", "path": "/contract", "value": {"shape": "scalar"}}, "operation_path"), + ({"op": "set", "metric_id": "m1", "path": "/kind", "value": "rule"}, "operation_path"), + ({"op": "set", "metric_id": "m1", "path": "/open_questions", "value": ["x"]}, "operation_path"), + ({"op": "set", "metric_id": "m1", "path": "unit", "value": "元"}, "operation_path"), + ({"op": "set", "metric_id": "m1", "path": "/definition", "value": {"text": "整份换"}}, "operation_path"), + ({"op": "patch", "metric_id": "m1", "path": "/unit", "value": "元"}, "operation_invalid"), + ({"op": "set", "metric_id": "m9", "path": "/unit", "value": "元"}, "operation_metric"), + ({"op": "set", "metric_id": "m1", "path": "/decimals", "value": "2"}, "operation_value"), + ({"op": "set", "metric_id": "m1", "path": "/name", "value": " "}, "operation_value"), + ({"op": "set", "metric_id": "m1", "path": "/name", "value": 3}, "operation_value"), +]) +async def test_illegal_operations_are_refused_with_a_specific_reason( + client, documents, datasource, monkeypatch, fake_trial, operation, code): + body = await ready_draft(client, documents, datasource, monkeypatch) + before = await _graph_of(body["workflow_id"]) + res = await change(client, body, [operation]) + assert res.status_code == 422, res.text + assert res.json()["code"] == code, res.text + assert res.json()["field"] == "operations" and res.json()["operation"] == 0 + assert res.json()["detail"] # 一句具体的话,不是空壳 + assert await _versions(body["workflow_id"]) == [1] + assert await _graph_of(body["workflow_id"]) == before + + +async def test_the_whole_batch_is_atomic(client, documents, datasource, monkeypatch, fake_trial): + """一条不合规,整批都不落地:前面那条合规的也不能半落进去(4.2 的原子性)。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + before = await _graph_of(body["workflow_id"]) + res = await change(client, body, [ops_set("m1", "/unit", "元"), ops_set("m1", "/definition/nope", "x")]) + assert res.status_code == 422, res.text + assert res.json()["operation"] == 1 + assert await _versions(body["workflow_id"]) == [1] + assert await _graph_of(body["workflow_id"]) == before + + # 换一条好的一起提交:两条都落 + ok = await change(client, body, [ops_set("m1", "/unit", "元"), ops_set("m1", "/grain", "order")]) + assert ok.status_code == 200, ok.text + metric = metric_of(await _graph_of(body["workflow_id"])) + assert metric["unit"] == "元" and metric["grain"] == "order" + assert await _versions(body["workflow_id"]) == [1, 2] + + +async def test_a_batch_that_ends_up_changing_nothing_creates_no_version( + client, documents, datasource, monkeypatch, fake_trial): + """先设后删(或者设成原来的值):内容没变,不新增版本,回执照实说没改动。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + same = await change(client, body, [ops_set("m1", "/unit", metric_of(await _graph_of(body["workflow_id"]))["unit"])]) + assert same.status_code == 200, same.text + assert same.json()["change"]["applied"] is False and same.json()["change"]["classification"] == "none" + assert same.json()["change"]["validation"]["invalidated"] is False + assert await _versions(body["workflow_id"]) == [1] + + churn = await change(client, same.json(), [ops_set("m1", "/grain", "order"), ops_remove("m1", "/grain")]) + assert churn.status_code == 200, churn.text + assert churn.json()["change"]["applied"] is False + assert [op["changed"] for op in churn.json()["change"]["operations"]] == [True, True] + assert await _versions(body["workflow_id"]) == [1] + + +async def test_a_missing_definition_object_is_created_by_set_and_ignored_by_remove(client): + """指标上还没有 definition 对象:set /definition/… 把它建出来;remove 是「本来就没有」——无变化,不是路径非法。""" + body = await bare_draft(client, [ + {"id": "m1", "name": "退款率", "unit": "%", "expression": "cell(nodes.fetch, 0, 'refund_rate')"}, + {"id": "m2", "name": "订单数", "definition": None, "expression": "cell(nodes.fetch, 0, 'orders')"}, + ]) + before = metric_of(await _graph_of(body["workflow_id"]), "m1") + res = await change(client, body, [ops_set("m1", "/definition/text", "只算已支付的订单"), + ops_set("m2", "/definition/exclusions", ["全额退款"])]) + assert res.status_code == 200, res.text + after = await _graph_of(body["workflow_id"]) + # 字段落在新建出来的对象里;这条指标上别的键一个不动 + assert metric_of(after, "m1")["definition"] == {"text": "只算已支付的订单"} + assert metric_of(after, "m2")["definition"] == {"exclusions": ["全额退款"]} + assert metric_of(after, "m1")["unit"] == before["unit"] + assert metric_of(after, "m1")["expression"] == before["expression"] + + # remove 一个本来就不存在的子字段:不新建对象、不新增版本,也不报路径非法 + none = await change(client, res.json(), [ops_remove("m2", "/definition/scope")]) + assert none.status_code == 200, none.text + assert none.json()["change"]["applied"] is False and none.json()["change"]["classification"] == "none" + assert metric_of(await _graph_of(body["workflow_id"]), "m2")["definition"] == {"exclusions": ["全额退款"]} + assert await _versions(body["workflow_id"]) == [1, 2] + + +async def test_a_definition_that_is_not_an_object_is_still_refused(client): + """definition 在、但不是对象(被人写成了字符串或数组):照旧拒——数据坏了就说清楚,不把原来的值丢掉。""" + body = await bare_draft(client, [ + {"id": "m1", "name": "退款率", "definition": "说明写在字符串里"}, + {"id": "m2", "name": "订单数", "definition": ["不是对象"]}, + ]) + before = await _graph_of(body["workflow_id"]) + for metric_id in ("m1", "m2"): + for operation in (ops_set(metric_id, "/definition/text", "改成别的"), ops_remove(metric_id, "/definition/text")): + res = await change(client, body, [operation]) + assert res.status_code == 422, res.text + assert res.json()["code"] == "operation_path" and "不是对象" in res.json()["detail"] + assert await _versions(body["workflow_id"]) == [1] + assert await _graph_of(body["workflow_id"]) == before + assert metric_of(await _graph_of(body["workflow_id"]), "m1")["definition"] == "说明写在字符串里" + + +# ========================================================================== +# 和整份换指标互斥;老路照旧 +# ========================================================================== + +async def test_field_operations_and_a_full_metrics_replacement_are_mutually_exclusive( + client, documents, datasource, monkeypatch, fake_trial): + body = await ready_draft(client, documents, datasource, monkeypatch) + metrics = copy.deepcopy(body["metrics"]) + res = await client.patch(patch_url(body["id"]), + json={"metrics": metrics, "operations": [ops_set("m1", "/unit", "元")], + "expected_revision": body["revision"]}) + assert res.status_code == 422, res.text + assert res.json()["code"] == "change_conflict" + everything = await client.patch(patch_url(body["id"]), + json={"resolved": [], "operations": [ops_set("m1", "/unit", "元")], + "expected_revision": body["revision"]}) + assert everything.status_code == 422 and everything.json()["code"] == "change_conflict" + assert await _versions(body["workflow_id"]) == [1] + + +async def test_a_target_naming_another_workflow_is_refused_even_without_a_card( + client, documents, datasource, monkeypatch, fake_trial): + """target.workflow_id 只要给了就必须是这份草稿自己的:没给 card_id 也一样拒(两条写路径同一套定位)。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + elsewhere = await change(client, body, [ops_set("m1", "/unit", "元")], target={"workflow_id": "wf-elsewhere"}) + assert elsewhere.status_code == 409, elsewhere.text + assert elsewhere.json()["code"] == "target_mismatch" and "target" == elsewhere.json()["field"] + + metrics = copy.deepcopy(body["metrics"]) + metrics[0]["unit"] = "元" + whole = await client.patch(patch_url(body["id"]), + json={"metrics": metrics, "expected_revision": body["revision"], + "target": {"workflow_id": "wf-elsewhere"}}) + assert whole.status_code == 409, whole.text + assert whole.json()["code"] == "target_mismatch" + assert await _versions(body["workflow_id"]) == [1] + + # 指对工作流、不指卡:图上只有一张可写的卡,照常改 + ok = await change(client, body, [ops_set("m1", "/unit", "元")], target={"workflow_id": body["workflow_id"]}) + assert ok.status_code == 200, ok.text + assert metric_of(await _graph_of(body["workflow_id"]))["unit"] == "元" + + +async def test_the_old_metrics_path_is_unchanged(client, documents, datasource, monkeypatch, fake_trial): + """整份换指标照旧(回执不带 change 段);没接管到工作流上的老草稿照旧只改 payload,字段操作落不到图上。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + metrics = copy.deepcopy(body["metrics"]) + metrics[0]["name"] = "整份换过的" + res = await client.patch(patch_url(body["id"]), + json={"metrics": metrics, "expected_revision": body["revision"]}) + assert res.status_code == 200, res.text + assert res.json()["metrics"][0]["name"] == "整份换过的" and res.json()["version"] == 2 + assert "change" not in res.json() + + legacy_id = uuid.uuid4().hex[:32] + async with SessionLocal() as session: + session.add(CaliberDraft(id=legacy_id, title="老草稿", status="ready", + payload={"metrics": [{"id": "m1", "name": "旧指标"}], "open_questions": []})) + await session.commit() + try: + refused = await client.patch(patch_url(legacy_id), + json={"operations": [ops_set("m1", "/unit", "元")]}) + assert refused.status_code == 409, refused.text + assert refused.json()["code"] == "change_unavailable" + ok = await client.patch(patch_url(legacy_id), json={"metrics": [{"id": "m1", "name": "改过的"}]}) + assert ok.status_code == 200 and ok.json()["metrics"][0]["name"] == "改过的" + finally: + async with SessionLocal() as session: + row = await session.get(CaliberDraft, legacy_id) + if row is not None: + await session.delete(row) + await session.commit() + + +# ========================================================================== +# 同一语义变化:画布和 operations 一致,旧试跑都过期 +# ========================================================================== + +async def test_the_same_change_via_the_canvas_and_via_operations_agree( + client, documents, datasource, monkeypatch, fake_trial): + """E08:同一个语义改动,从画布(整图保存)和从工作台(operations)提交得到同一张执行图,旧试跑都判过期。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + wid = body["workflow_id"] + assert (await client.get(patch_url(body["id"]))).json()["trial"]["status"] == "succeeded" + v1 = await _graph_of(wid) + + # 画布那条路:拿 v1 的图,人工把同一个字段改成同一个值,整图保存 + canvas_graph = copy.deepcopy(v1) + metric_of(canvas_graph)["time_field"] = "paid_at" + saved = await client.patch(f"/api/workflows/{wid}", + json={"graph": canvas_graph, "expected_revision": body["revision"]}) + assert saved.status_code == 200 and saved.json()["version"] == 2, saved.text + canvas_after = await _graph_of(wid) + assert (await client.get(patch_url(body["id"]))).json()["trial"]["status"] == "stale" + + # operations 那条路:回到 v1 的图上改同一个字段(回滚出一版,再按字段改) + rolled = await client.post(f"/api/workflows/{wid}/versions/1/restore", json={"expected_revision": 2}) + assert rolled.status_code == 200 and rolled.json()["version"] == 3, rolled.text + assert await _graph_of(wid) == v1 + changed = await change(client, {**body, "revision": 3}, [ops_set("m1", "/time_field", "paid_at")]) + assert changed.status_code == 200, changed.text + ops_after = await _graph_of(wid) + assert changed.json()["change"]["applied"] is True + assert (await client.get(patch_url(body["id"]))).json()["trial"]["status"] == "stale" + + # 两条路得到的是同一张执行图:图哈希可以不同(版本快照元数据),执行指纹一样 + assert execution_hash(ops_after) == execution_hash(canvas_after) + assert metric_of(ops_after) == metric_of(canvas_after) + + +# ========================================================================== +# K02 的写入保护:字段变更一条不少 +# ========================================================================== + +async def test_field_operations_need_a_base_revision_and_refuse_a_stale_page( + client, documents, datasource, monkeypatch, fake_trial): + """E01 的字段操作版:没带基准版本 409 revision_required;旧页面 409 stale_revision,先写进去的不被盖掉。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + missing = await client.patch(patch_url(body["id"]), json={"operations": [ops_set("m1", "/unit", "元")]}) + assert missing.status_code == 409, missing.text + assert missing.json()["code"] == "revision_required" and missing.json()["current_version"] == 1 + assert await _versions(body["workflow_id"]) == [1] + + first = await change(client, body, [ops_set("m1", "/unit", "元")]) + assert first.status_code == 200 and first.json()["version"] == 2, first.text + stale = await change(client, body, [ops_set("m1", "/unit", "万元")]) # 还拿着 v1 + assert stale.status_code == 409, stale.text + assert stale.json()["code"] == "stale_revision" and stale.json()["current_version"] == 2 + assert await _versions(body["workflow_id"]) == [1, 2] + assert metric_of(await _graph_of(body["workflow_id"]))["unit"] == "元" + # 指到没有的卡:拒(K02 的卡级定位一起管着这条路) + missing_card = await change(client, body, [ops_set("m1", "/unit", "元")], target={"card_id": "card-nope"}) + assert missing_card.status_code == 409 and missing_card.json()["code"] == "card_not_found" + + +async def test_the_same_request_id_replays_and_different_operations_conflict( + client, documents, datasource, monkeypatch, fake_trial): + """指纹包含 operations:同键同内容重放不新增版本;同键换了字段或换了值都算另一次请求(409)。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + request = [ops_set("m1", "/unit", "元")] + first = await change(client, body, request, request_id="k03-0001") + assert first.status_code == 200 and first.json()["version"] == 2, first.text + assert first.json().get("replayed") is None + + # 同键同内容:基准版本这时已经过期,但幂等在版本检查之前判,照旧成功,不再新增版本 + again = await change(client, body, request, request_id="k03-0001") + assert again.status_code == 200, again.text + assert again.json()["replayed"] is True and again.json()["version"] == 2 + assert await _versions(body["workflow_id"]) == [1, 2] + + # 同键、换了路径:内容不同 → 冲突 + other_path = await change(client, body, [ops_set("m1", "/grain", "元")], request_id="k03-0001") + assert other_path.status_code == 409, other_path.text + assert other_path.json()["code"] == "idempotency_conflict" + # 同键、同一个字段换了值:内容不同 → 冲突(值算了进去) + other_value = await change(client, body, [ops_set("m1", "/unit", "万元")], request_id="k03-0001") + assert other_value.status_code == 409 and other_value.json()["code"] == "idempotency_conflict" + # 同键、同一批换顺序:顺序是内容的一部分(同一条指标上的操作有先后)→ 冲突 + reordered = await change(client, body, [ops_set("m1", "/grain", "order"), ops_set("m1", "/unit", "元")], + request_id="k03-0001") + assert reordered.status_code == 409 and reordered.json()["code"] == "idempotency_conflict" + # 省略 value 和写 null 是两件事,指纹也分得开 + assert api_ledger_fingerprint(body, request) != api_ledger_fingerprint( + body, [ops_set("m1", "/unit", None)]) + assert await _versions(body["workflow_id"]) == [1, 2] + + +def api_ledger_fingerprint(body: dict, operations: list[dict]) -> str: + """同一个 request_id 的两次请求,指纹按内容算(把 pydantic 的排除未设置行为也一起算进去)。""" + payload = api_ledger.DraftPatchIn(operations=operations, expected_revision=body["revision"]) + return api_ledger._patch_fingerprint(payload, body["card_id"]) + + +async def test_old_request_ids_still_replay_after_the_operations_field_landed( + client, documents, datasource, monkeypatch, fake_trial): + """不带 operations 的老请求算出来的还是原来那一份指纹:升级前记下的 request_id 不会被判成「同键不同内容」。""" + from app.apps.versions import write_fingerprint + + body = await ready_draft(client, documents, datasource, monkeypatch) + metrics = copy.deepcopy(body["metrics"]) + metrics[0]["name"] = "老请求" + payload = api_ledger.DraftPatchIn(metrics=metrics, expected_revision=body["revision"]) + before_k03 = write_fingerprint({"title": None, "metrics": metrics, "resolved": None, "card": body["card_id"]}) + assert api_ledger._patch_fingerprint(payload, body["card_id"]) == before_k03 + + +async def test_two_operations_with_the_same_key_at_once_write_once( + client, documents, datasource, monkeypatch, fake_trial): + """同一个 request_id 的两路字段变更同时发:只落一版,两边都是 200。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + payload = {"operations": [ops_set("m1", "/unit", "元")], "expected_revision": body["revision"], + "request_id": "k03-race"} + url = patch_url(body["id"]) + first, second = await asyncio.gather(client.patch(url, json=payload), client.patch(url, json=payload)) + assert sorted(res.status_code for res in (first, second)) == [200, 200], (first.text, second.text) + assert await _versions(body["workflow_id"]) == [1, 2] + assert [res.json().get("replayed") for res in (first, second)].count(True) <= 1 + assert metric_of(await _graph_of(body["workflow_id"]))["unit"] == "元" + + +async def test_two_field_changes_at_once_do_not_lose_an_update( + client, documents, datasource, monkeypatch, fake_trial): + """两路各自改一处、都基于同一版同时发:CAS 只让一路落成,另一路 409 stale_revision(不静默盖掉)。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + wid = body["workflow_id"] + url = patch_url(body["id"]) + first, second = await asyncio.gather( + client.patch(url, json={"operations": [ops_set("m1", "/unit", "元")], + "expected_revision": body["revision"], "request_id": "k03-a"}), + client.patch(url, json={"operations": [ops_set("m1", "/unit", "万元")], + "expected_revision": body["revision"], "request_id": "k03-b"})) + assert sorted(res.status_code for res in (first, second)) == [200, 409], (first.text, second.text) + refused = first if first.status_code == 409 else second + assert refused.json()["code"] in ("stale_revision", "idempotency_conflict") + assert refused.json()["current_version"] == 2 + assert await _versions(wid) == [1, 2] + assert metric_of(await _graph_of(wid))["unit"] in ("元", "万元") + + +# ========================================================================== +# 仓储:薄边界,图上改 +# ========================================================================== + +def test_the_repository_hides_the_graph_and_refuses_what_is_not_a_source_card(): + graph = {"nodes": [ + {"id": "card", "type": "metrics", "data": {"label": "口径卡", "config": {"metrics": [ + {"id": "m1", "name": "退款率", "unit": "%"}, {"id": "m2", "name": "订单数"}]}}}, + {"id": "chained", "type": "metrics", "data": {"label": "转抄", "config": { + "caliber_from": {"workflow_id": "w", "workflow_version": 1}, "metrics": []}}}, + {"id": "fetch", "type": "tool", "data": {"label": "取数", "config": {"tool": "db_query__shop"}}}, + ], "edges": []} + repo = GraphBackedCaliberRepository(graph, card_id="card") + assert repo.card.node_id == "card" and repo.card.title == "口径卡" + assert repo.ids() == ["m1", "m2"] + + # 读出来的是深拷贝:改它不影响图 + metric = repo.metric("m1") + metric["unit"] = "改过的" + assert repo.metric("m1")["unit"] == "%" + with pytest.raises(MetricGone): + repo.metric("m9") + + # 换指标交回的是整张图的深拷贝,别的节点带着走,指标顺序不变 + new_graph = repo.replace_metrics({"m1": {**repo.metric("m1"), "unit": "元"}}) + assert [node["id"] for node in new_graph["nodes"]] == ["card", "chained", "fetch"] + assert new_graph["nodes"][2] == graph["nodes"][2] and new_graph is not graph + assert [m["id"] for m in new_graph["nodes"][0]["data"]["config"]["metrics"]] == ["m1", "m2"] + assert new_graph["nodes"][0]["data"]["config"]["metrics"][0]["unit"] == "元" + assert graph["nodes"][0]["data"]["config"]["metrics"][0]["unit"] == "%" + with pytest.raises(MetricGone): + repo.replace_metrics({"m9": {"id": "m9"}}) + + with pytest.raises(CaliberGone): + GraphBackedCaliberRepository(graph, card_id="chained") + with pytest.raises(CaliberGone): + GraphBackedCaliberRepository(graph, card_id="fetch") + with pytest.raises(CaliberGone): + GraphBackedCaliberRepository(graph, card_id="nope") + + +def test_the_operation_whitelist_covers_the_fields_that_really_exist(): + """白名单落在指标真有的字段上:顶层路径按 data/caliber_identity.SEMANTIC_FIELDS 对齐(同义词是展示字段)。""" + from app.data.caliber_identity import SEMANTIC_FIELDS + + top = {path[1:] for path in changes.FIELDS if path.count("/") == 1} + assert top <= set(SEMANTIC_FIELDS) | {"synonyms"} + # 起草阶段真正会写进指标的字段(app/ledger/draftplan.METRIC_FIELDS)都要能按字段改 + assert {"id", "name", "synonyms", "unit", "decimals", "expression", "grain", "time_field", + "numerator", "denominator", "dimensions", "filters"} - {"id"} <= top + assert {path for path in changes.FIELDS if path.startswith("/definition/")} == { + "/definition/text", "/definition/scope", "/definition/exclusions"} + # 身份、证据归属和治理归属都在「不能改」那一栏里 + assert {"/id", "/definition/citations", "/definition/owner", "/definition/effective_from"} <= set(changes.FORBIDDEN) diff --git a/backend/tests/test_caliber_query_tool.py b/backend/tests/test_caliber_query_tool.py new file mode 100644 index 00000000..908abf86 --- /dev/null +++ b/backend/tests/test_caliber_query_tool.py @@ -0,0 +1,1487 @@ +"""K10:父 Run 的口径查询工具(`caliber_query`)与父子 Run 的证据接入。 + +这份文件盯住这几条: + +1. **工具是真的、参数是固定的。** 登记表里有 `caliber_query`(不是 `db_query__` 前缀那类动态工具),参数只有口径身份 + (workflow / card)、要算的指标和这次入口的类型化取值;用途、主体、父 Run 身份、固定的数据版本都由父 Run 的上下文定, + 参数里没有也传不了。 +2. **证据接回父 Run。** 用父 Run 的上下文执行(`ToolContext`),当场 await 收尾;派生的探针运行是**明确的子运行** + (origin 里记 parent_run_id),父 Run 的节点把每条 query artifact 记进自己的台账(query_id / execution_id / attempt、 + 来源、列与行数、截断都在)——一次交回**多条**查询(queries 数组)不会只记第一条。 +3. **伪造、跨运行、别的种类的工件一律拒绝。** 每条 query artifact 必须是这次授权的父运行自己落的,或它明确派生的子运行 + 落下的,且 kind=query_snapshot(capabilities.registry.snapshot_owned)。 +4. **同一指标工作台与父 Run 是同一种说法。** 同一份口径、同一组指标与入口,HTTP 工作台(compose)与父 Run 拿到的发布 + 清单、结果类型、参数解释一致。 +5. **父 Run 的边界跟着走。** 遮罩、截断、上传/记录源版本固定、只读、预算、复算要的材料;正式父 Run 走 formal judge, + 交互(compose)拿不到正式身份;超时、失败都不是成功。 + +数据全是合成的(一个临时 SQLite 库、几条合成标量指标),不连真实业务库;这些指标不是任何真实业务口径。 +""" +from __future__ import annotations + +import asyncio +import copy +import json +import sqlite3 +import uuid +from typing import Any + +import pytest +from httpx import ASGITransport, AsyncClient +from langchain_core.messages import AIMessage, ToolMessage +from sqlalchemy import select + +from app.apps import publications +from app.db.base import SessionLocal +from app.db.models import Artifact, DataSource, Run, RunEvent +from app.engine.runner import run_manager +from app.ledger import querycore +from app.main import app +from app.records import store +from app.records.tables import columns_of, path_of +from tests import ledger_samples as S +from tests.publication_samples import add_record, add_version, confirm, make_workflow, publish + +#: 这一版口径卡的节点 id(源头口径卡) +CARD = "card" +#: 取数窗口:start(含)/ end(不含) +WINDOW = "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'" +ROWS = [ + (1, "east", "paid", 100.0, 2, "2026-09-02"), + (2, "east", "paid", 50.0, 1, "2026-09-03"), + (3, "west", "refunded", 30.0, 3, "2026-09-04"), + (4, "west", "paid", 20.0, 4, "2026-09-07"), + (5, "east", "open", 12.5, 5, "2026-09-07"), + (6, "west", "paid", 70.0, 6, "2026-10-02"), + (7, "east", "paid", 5.0, 7, "2026-08-31"), +] +#: 窗口内的期望值(2026-09-01 ≤ paid_at < 2026-10-01,只算 paid) +WINDOW_SUM = 170.0 +INPUTS = {"start": "2026-09-01", "end": "2026-10-01"} + + +def build_db(path) -> None: + db = sqlite3.connect(path) + db.executescript("CREATE TABLE orders (id INTEGER PRIMARY KEY, region TEXT, status TEXT, amount REAL, " + "qty INTEGER, paid_at TEXT);") + db.executemany("INSERT INTO orders VALUES (?, ?, ?, ?, ?, ?)", ROWS) + db.commit() + db.close() + + +async def fresh_source(tmp_path) -> str: + """每个用例一个名字不同的数据源(候选口径按数据源预筛,别的用例的口径不会混进来)。""" + path = tmp_path / "caliber_query.db" + build_db(path) + S.CURRENT["source"] = f"cq_{uuid.uuid4().hex[:8]}" + await S.set_source(path) + return S.CURRENT["source"] + + +def graph(*, sales_limit: int | None = None, grouped: bool = False) -> dict[str, Any]: + """入口 → 两条取数 → 口径卡 → 报告 → 出口(报告节点只在原图里,探针图不跑它)。 + + grouped=True 时 sales 那条按大区分组、可以给 limit:用来测截断(结果被截短照实记进台账)。""" + sales_sql = (f"SELECT region, SUM(amount) AS gmv, SUM(qty) AS units FROM orders WHERE status = 'paid' {WINDOW} " + "GROUP BY region" if grouped else + f"SELECT SUM(amount) AS gmv, SUM(qty) AS units FROM orders WHERE status = 'paid' {WINDOW}") + sales_args: dict[str, Any] = {"sql": sales_sql} + if sales_limit is not None: + sales_args["limit"] = sales_limit + return S.chain( + S.node("start", "input", fields=[ + {"name": "start", "type": "string", "required": True, "description": "开始日期(含)"}, + {"name": "end", "type": "string", "required": True, "description": "结束日期(不含)"}, + ]), + S.node("sales", "tool", tool=S.tool(), args=sales_args), + S.node("shared", "tool", tool=S.tool(), + args={"sql": f"SELECT SUM(amount) AS total, MAX(amount) AS peak FROM orders " + f"WHERE status = 'paid' {WINDOW}"}), + S.node(CARD, "metrics", caliber="合成周销售", caliber_version="v1", metrics=[ + {"id": "gmv", "name": "销售额", "unit": "元", "decimals": 2, "format": "thousands", + "expression": "cell(nodes.sales, 0, 'gmv')"}, + {"id": "units", "name": "件数", "unit": "件", "expression": "cell(nodes.sales, 0, 'units')"}, + {"id": "peak", "name": "最大单笔", "unit": "元", "decimals": 2, + "expression": "cell(nodes.shared, 0, 'peak')"}, + ]), + S.node("write", "report", instructions="写周销售"), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.write.text }}"}]), + ) + + +def twin_graph() -> dict[str, Any]: + """两个取数节点写**同一条 SQL**、读同一张表、同一批数据(内容寻址下会落到同一个工件 id):两条不同的逻辑查询。 + + 这是「同 artifact 对应不同逻辑 query」的反例:按工件 id 去重的证据索引会把它们并成一条。""" + sql = f"SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' {WINDOW}" + metrics = [{"id": "left", "name": "甲", "unit": "元", "expression": "cell(nodes.one, 0, 'gmv')"}, + {"id": "right", "name": "乙", "unit": "元", "expression": "cell(nodes.two, 0, 'gmv')"}] + return S.chain( + S.node("start", "input", fields=[{"name": "start", "type": "string", "required": True}, + {"name": "end", "type": "string", "required": True}]), + S.node("one", "tool", tool=S.tool(), args={"sql": sql}), + S.node("two", "tool", tool=S.tool(), args={"sql": sql}), + S.node(CARD, "metrics", caliber="合成双查", caliber_version="v1", metrics=metrics), + S.node("write", "report", instructions="写周销售"), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.write.text }}"}]), + ) + + +def parent_graph(workflow_id: str, *, metric_ids: list[str] | None = None, card: str = CARD, + inputs: dict[str, Any] | None = None, gate: bool = False) -> dict[str, Any]: + """父 Run 的图:入口 →(可选的人工确认)→ 调用工具(caliber_query)→ 出口。""" + parts = [S.node("start", "input")] + if gate: + parts.append(S.node("gate", "human", mode="approve", title="看一眼")) + parts.append(S.node("look", "tool", tool=querycore.CALIBER_QUERY, args={ + "workflow": workflow_id, "card": card, + "metric_ids": metric_ids or ["gmv", "peak"], + "inputs": inputs if inputs is not None else dict(INPUTS)})) + parts.append(S.node("out", "output", fields=[{"name": "答", "value": "{{ nodes.look.ok }}"}])) + return S.chain(*parts) + + +@pytest.fixture(autouse=True) +async def engine_up(tmp_path): + await run_manager.setup() + await fresh_source(tmp_path) + yield + await run_manager.shutdown() + + +@pytest.fixture +async def client(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c: + yield c + + +async def published(client: AsyncClient, *, sales_limit: int | None = None, grouped: bool = False) -> dict: + """建一份已发布的口径(走 K07 的真实发布入口),返回资产。""" + asset = await make_workflow(graph=graph(sales_limit=sales_limit, grouped=grouped)) + await publish(client, asset) + return asset + + +async def run_parent(asset: dict, *, inputs: dict[str, Any] | None = None, metric_ids: list[str] | None = None, + data_versions: dict[str, Any] | None = None, options: dict[str, Any] | None = None, + run_class: str = "exploratory") -> Run: + """起一次父 Run(走调用工具节点那条路),等它收尾。""" + run = await run_manager.start(graph=parent_graph(asset["workflow_id"], inputs=inputs, metric_ids=metric_ids), + input_payload={}, run_class=run_class, data_versions=data_versions, + options=options) + return await settled(run.id) + + +async def run_once(asset: dict, *, metric_ids: list[str], inputs: dict[str, Any] | None = None, **kw: Any): + """走服务入口跑一次(HTTP 之外的那条路),等 K09 的执行结果。""" + async with SessionLocal() as session: + return await querycore.execute(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=metric_ids, + inputs=inputs if inputs is not None else dict(INPUTS), **kw) + + +async def settled(run_id: str) -> Run: + for _ in range(600): + async with SessionLocal() as session: + row = await session.get(Run, run_id) + if row.status in querycore.TERMINAL_RUN_STATUSES: + return row + await asyncio.sleep(0.05) + raise AssertionError(f"运行 {run_id} 没有结束:{row.status}") + + +async def events_of(run_id: str, etype: str) -> list[dict[str, Any]]: + async with SessionLocal() as session: + rows = (await session.execute(select(RunEvent).where(RunEvent.run_id == run_id, + RunEvent.type == etype) + .order_by(RunEvent.seq))).scalars().all() + return [dict(r.data or {}) for r in rows] + + +async def tool_end(run_id: str) -> dict[str, Any]: + [data] = await events_of(run_id, "tool.end") + return data + + +async def tool_result(run_id: str, node_id: str = "look") -> dict[str, Any]: + """调用工具节点的**完整**产出:tool.end 的 preview 截到 2000 个字符,读不全 JSON(K10 的结果里带几条查询)。""" + from app.engine.evidence_reader import read_sealed + + sealed = await read_sealed(run_id) + payload = sealed.payload_of([node_id]) + assert isinstance(payload, dict), "调用工具节点没有产出" + return payload + + +async def finished_evidence(run_id: str, node_id: str = "look") -> list[dict[str, Any]]: + async with SessionLocal() as session: + rows = (await session.execute(select(RunEvent).where(RunEvent.run_id == run_id, + RunEvent.type == "node.finished") + .order_by(RunEvent.seq))).scalars().all() + for row in rows: + data = dict(row.data or {}) + if row.node_id == node_id and data.get("evidence"): + return list(data["evidence"]) + return [] + + +# ========================================================================== +# 1、工具是真的:登记表里有它、参数固定、不是 db_query__ 前缀 +# ========================================================================== + + +async def test_the_tool_is_registered_with_fixed_parameters(): + from app.capabilities.registry import is_platform_query + from app.tools.registry import all_specs + + spec = all_specs()[querycore.CALIBER_QUERY] + assert spec.category and spec.description and not spec.dangerous and not spec.writes_state + assert spec.effect == "read", "口径查询是只读的:不写外部系统、不该要确认" + assert set(spec.args_schema.model_fields) == {"workflow", "card", "metric_ids", "inputs"} + # 用途、主体、版本、预算都不在参数里:由父 Run 的上下文定,模型改不了 + assert not set(spec.args_schema.model_fields) & {"purpose", "role", "actor", "version", "budget", "trace"} + assert is_platform_query(querycore.CALIBER_QUERY), "口径查询的结果要能当查询快照作证" + assert not querycore.CALIBER_QUERY.startswith("db_query__"), "它是真实工具,不是数据源那类动态工具" + + +async def test_it_needs_a_parent_run(): + from app.tools.registry import ToolContext + + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.caliber_query(ToolContext(), workflow="w", card=CARD, metric_ids=["gmv"], inputs={}) + assert caught.value.code == querycore.NO_PARENT + + +# ========================================================================== +# 2、证据接回父 Run:子运行、多条查询、执行身份 +# ========================================================================== + + +async def test_the_parent_run_records_every_query_of_one_call(client): + asset = await published(client) + parent = await run_parent(asset, metric_ids=["gmv", "peak"]) + assert parent.status == "succeeded", parent.error + + end = await tool_end(parent.id) + assert end["tool"] == querycore.CALIBER_QUERY + # 一次调用交回两条查询(sales、shared):tool.end 上两条的工件 id 都在 + assert len(end["query_artifacts"]) == 2 and end["query_artifact"] == end["query_artifacts"][0] + + entries = [e for e in await finished_evidence(parent.id) if e.get("kind") == "query"] + assert [e["tool"] for e in entries] == [querycore.CALIBER_QUERY] * 2 + assert {e["artifact"] for e in entries} == set(end["query_artifacts"]) + child_id = (await tool_result(parent.id))["run_id"] + for entry in entries: + assert entry["columns"] and entry["rows"] and entry["truncated"] is False + # 源名写在和数据源查询同一个位置(证据面板、遮罩按它认源) + assert entry["source"] == S.CURRENT["source"] + # 出处是这一版这一张图里的那条取数,不是父 Run 的节点 + assert entry["origin"]["workflow_id"] == asset["workflow_id"] and entry["origin"]["version"] == 1 + assert entry["origin"]["node_id"] in ("sales", "shared") + # 执行身份三件套齐(K10):执行号记的是真的执行那次 SQL 的运行(派生的子运行),不是父 Run + assert entry["query_id"] and entry["execution_id"] and entry["attempt"] >= 1 + assert child_id in entry["execution_id"], "执行身份带上真的执行那次,别把两次调用的执行混成一个" + # 复算要的材料跟着条目走:这次参数输入的哈希与源模板哈希(值本身、SQL 正文都不进台账) + assert entry["parameters"]["inputs_hash"] and entry["parameters"]["template_hash"] + assert {e["query_id"] for e in entries} == {f"{asset['workflow_id']}:sales", f"{asset['workflow_id']}:shared"} + + # 父 Run 的封存证据里认得出这两条查询(报告目录、证据面板从这里出发) + from app.engine.evidence_reader import read_sealed + + sealed = await read_sealed(parent.id) + assert {e["artifact"] for e in entries} <= set(sealed.queries) + for artifact in end["query_artifacts"]: + assert sealed.queries[artifact]["node_id"] == "look" + + +async def test_the_probe_run_is_an_explicit_child_of_the_parent(client): + asset = await published(client) + parent = await run_parent(asset) + end = await tool_end(parent.id) + child_id = (await tool_result(parent.id))["run_id"] + assert child_id, "结果里要给出子运行的 id" + async with SessionLocal() as session: + child = await session.get(Run, child_id) + assert child is not None and child.id != parent.id and child.run_class == "exploratory" + origin = child.origin or {} + assert origin["service"] == "querycore" and origin["purpose"] == querycore.DEFAULT_PURPOSE + assert origin["parent_run_id"] == parent.id, "子运行的来源里必须记着父运行,父子关系不能丢" + assert origin["manifest"] and origin["selection_hash"] and origin["closure_hash"], "复算要的材料都在" + assert child.options.get("read_only_data") is True, "派生的子运行照旧一律只读" + + +async def test_two_identical_calls_get_different_execution_ids(client): + """同样的参数、同样的 SQL 调两次:两个子运行,执行身份各不相同(工件按内容寻址,可以是同一件)。""" + from app.tools.registry import ToolContext + + asset = await published(client) + ctx = ToolContext(run_id="parent-fixed", node_id="look") + first = await querycore.caliber_query(ctx, workflow=asset["workflow_id"], card=CARD, + metric_ids=["gmv"], inputs=dict(INPUTS)) + second = await querycore.caliber_query(ctx, workflow=asset["workflow_id"], card=CARD, + metric_ids=["gmv"], inputs=dict(INPUTS)) + assert first["ok"] and second["ok"] + assert first["run_id"] != second["run_id"], "每次调用派生一次自己的子运行" + left, right = first["queries"][0], second["queries"][0] + assert left["query_id"] == right["query_id"], "逻辑查询是同一条" + assert left["execution_id"] != right["execution_id"], "同一条 SQL 执行两次,执行身份必须不同" + + +async def test_two_identical_executions_in_one_run_are_not_merged(client): + """同一个父 Run 里两个节点跑同一条 SQL:台账里两条各记各的执行,不合并成一条。""" + asset = await published(client) + args = {"workflow": asset["workflow_id"], "card": CARD, "metric_ids": ["gmv"], "inputs": dict(INPUTS)} + graph = S.chain( + S.node("start", "input"), + S.node("one", "tool", tool=querycore.CALIBER_QUERY, args=dict(args)), + S.node("two", "tool", tool=querycore.CALIBER_QUERY, args=dict(args)), + S.node("out", "output", fields=[{"name": "答", "value": "{{ nodes.two.ok }}"}]), + ) + run = await run_manager.start(graph=graph, input_payload={}) + row = await settled(run.id) + assert row.status == "succeeded", row.error + entries = ([e for e in await finished_evidence(row.id, "one") if e.get("kind") == "query"] + + [e for e in await finished_evidence(row.id, "two") if e.get("kind") == "query"]) + assert len(entries) == 2, "两次执行各记一条" + assert len({e["execution_id"] for e in entries}) == 2, "同一份 SQL 跑两次,各记各的执行身份" + assert len({e["query_id"] for e in entries}) == 1, "逻辑查询是同一条" + + +# ========================================================================== +# 3、伪造 / 跨运行 / 别的种类:一律不当证据 +# ========================================================================== + + +async def test_a_forged_or_cross_run_artifact_is_refused(client): + """名字对了,工件还得是这次父运行(或它明确派生的子运行)落下的 query_snapshot。""" + from app.capabilities.registry import snapshot_owned + from app.core.artifact_store import put_json + + asset = await published(client) + parent = await run_parent(asset) + [artifact] = (await tool_end(parent.id))["query_artifacts"][:1] + # 真的:父 Run 明确派生的子运行落下的查询快照 + assert await snapshot_owned(artifact, parent.id, querycore.CALIBER_QUERY) + # 别的运行落下的同一件:不认 + assert not await snapshot_owned(artifact, "another-run", querycore.CALIBER_QUERY) + # 伪造的工件 id:不认 + assert not await snapshot_owned("f" * 64, parent.id, querycore.CALIBER_QUERY) + + # 种类不对(同一件内容、父运行自己落下的 tool_snapshot):不认 + async with SessionLocal() as session: + snap = (await session.execute(select(Artifact).where(Artifact.id == artifact))).first() + wrong_kind = await put_json({"x": 1}, kind="tool_snapshot", run_id=parent.id) + assert wrong_kind != artifact + assert not await snapshot_owned(wrong_kind, parent.id, querycore.CALIBER_QUERY), "不是 query_snapshot 的不当作证" + assert snap is not None, "子运行那件工件在工件表里记着" + + +async def test_a_forged_tool_result_does_not_become_evidence(client, monkeypatch): + """调用工具节点交回一份拼出来的 caliber 结果(工件是别人的):不进台账、tool.end 上也不带。""" + from app.engine.nodes import tools as tool_node + + asset = await published(client) + + async def forged_call_tool(*_a, **_k): + return {"tool": querycore.CALIBER_QUERY, "kind": querycore.CALIBER_QUERY, "ok": True, "run_id": "made-up", + "queries": [{"artifact": "a" * 64, "source": {"workflow_id": asset["workflow_id"], "version": 1, + "node_id": "sales"}, + "columns": ["gmv"], "row_count": 1, "truncated": False, + "query_id": "made-up:sales", "execution_id": "made-up:sales#e1", "attempt": 1}]} + + monkeypatch.setattr(tool_node, "call_tool", forged_call_tool) + parent = await run_parent(asset) + assert parent.status == "succeeded", parent.error + end = await tool_end(parent.id) + assert "query_artifact" not in end and "query_artifacts" not in end + assert [e for e in await finished_evidence(parent.id) if e.get("kind") == "query"] == [] + + +# ========================================================================== +# 4、同一指标工作台与父 Run 是同一种说法 +# ========================================================================== + + +async def test_the_workbench_and_the_parent_run_agree(client): + asset = await published(client) + res = await client.post("/api/ledger/querycore", json={ + "workflow_id": asset["workflow_id"], "card_id": CARD, "metric_ids": ["gmv", "peak"], "inputs": INPUTS}) + assert res.status_code == 200, res.text + bench = res.json() + assert bench["ok"] and bench["purpose"] == publications.PURPOSE_COMPOSE + + parent = await run_parent(asset, metric_ids=["gmv", "peak"]) + end = await tool_end(parent.id) + tool = await tool_result(parent.id) + + # 同一份发布清单、同一种结果类型、同一套参数解释 + assert tool["publication"] == bench["publication"] + assert tool["version"] == bench["version"] and tool["explicit_version"] == bench["explicit_version"] + assert [m["id"] for m in tool["metrics"]] == [m["id"] for m in bench["metrics"]] + assert [m["value"] for m in tool["metrics"]] == [m["value"] for m in bench["metrics"]] + assert tool["metrics"] == bench["metrics"] + assert tool["parameters"]["values"] == bench["parameters"]["values"] == INPUTS + assert tool["parameters"]["contract"] == bench["parameters"]["contract"] + assert tool["parameters"]["adapter"] == bench["parameters"]["adapter"] + assert tool["selection"]["closure_hash"] == bench["selection"]["closure_hash"] + assert tool["data"]["tables"] == bench["data"]["tables"] == ["orders"] + # 每条查询:逻辑身份、列、参数输入哈希、行数与截断一致(工件是两次运行各自的,不要求相同) + assert [(q["query_id"], q["columns"], q["truncated"]) for q in tool["queries"]] \ + == [(q["query_id"], q["columns"], q["truncated"]) for q in bench["queries"]] + assert [q["parameters"]["inputs_hash"] for q in tool["queries"]] \ + == [q["parameters"]["inputs_hash"] for q in bench["queries"]] + + +# ========================================================================== +# 5、父 Run 的边界:遮罩、截断、版本固定、只读、预算、formal +# ========================================================================== + + +async def test_masked_values_are_not_handed_out(client, tmp_path): + asset = await published(client) + await S.set_source(tmp_path / "caliber_query.db", options={"mask_columns": ["gmv"]}) + parent = await run_parent(asset, metric_ids=["gmv"]) + tool = await tool_result(parent.id) + [metric] = [m for m in tool["metrics"] if m["id"] == "gmv"] + assert metric.get("masked") is True and metric["value"] is None + assert tool["ok"] is False and querycore.METRIC_MASKED in [p["code"] for p in tool["problems"]] + assert "masked" not in json.dumps([{"id": m["id"], "v": m["value"]} for m in tool["metrics"]]) + + +async def test_truncated_results_are_reported_as_truncated(client): + asset = await published(client, grouped=True, sales_limit=1) + parent = await run_parent(asset, metric_ids=["gmv"]) + [entry] = [e for e in await finished_evidence(parent.id) if e.get("kind") == "query"] + assert entry["truncated"] is True, "结果被截短照实记进台账,不悄悄当完整结果" + assert entry["rows"] == 1, "台账里记的是快照里真的有多少行" + + +async def test_the_parent_run_pins_the_source_versions_into_the_child(client): + """父 Run 固定的上传/记录源版本照原样带进子运行:父子两段查的是同一版数据。""" + asset = await published(client) + pinned = {"src-1": {"snapshot": "snap-1", "name": "表格"}} + parent = await run_parent(asset, data_versions=pinned) + assert parent.data_versions == pinned + child_id = (await tool_result(parent.id))["run_id"] + async with SessionLocal() as session: + child = await session.get(Run, child_id) + assert child.data_versions == pinned, "子运行必须照父 Run 那一份固定,不能改用当前版本" + assert child.options.get("read_only_data") is True + + +async def test_a_timeout_is_not_a_success(client): + """父 Run 给的预算到点没跑完:交回 running + 子运行 id,ok=False,台账里一条查询都没有。""" + asset = await published(client) + parent = await run_parent(asset, options={querycore.BUDGET_OPTION: {"timeout_s": 0.0}}) + assert parent.status == "succeeded", parent.error + end = await tool_end(parent.id) + tool = await tool_result(parent.id) + assert tool["ok"] is False and tool["status"] == "running" and tool["run_id"] + assert [p["code"] for p in tool["problems"]] == [querycore.TIMEOUT] + assert "query_artifact" not in end + assert [e for e in await finished_evidence(parent.id) if e.get("kind") == "query"] == [] + + +async def test_a_refusal_is_a_tool_failure(client): + """口径不在(卡的名字写错):工具当场拒,节点失败并说清原因——不交回一份空结果冒充成功。""" + asset = await published(client) + parent = await run_parent(asset, metric_ids=["gmv"], inputs=dict(INPUTS)) + assert parent.status == "succeeded" + run = await run_manager.start(graph=parent_graph(asset["workflow_id"], card="nope", inputs=dict(INPUTS)), + input_payload={}) + row = await settled(run.id) + assert row.status == "failed" and querycore.CARD_MISSING in (row.error or "") + + +async def test_a_formal_parent_uses_the_formal_judge(client): + """正式父 Run:走 execute_formal 那一套(发布依据不齐就拒);交互(compose)拿不到正式身份。""" + from app.tools.registry import ToolContext + + asset = await published(client) # 有清单、没有验证记录与审阅 + compose = ToolContext(run_id="p1", node_id="look") + outcome = await querycore.caliber_query(compose, workflow=asset["workflow_id"], card=CARD, + metric_ids=["gmv"], inputs=dict(INPUTS)) + assert outcome["ok"] and outcome["purpose"] == publications.PURPOSE_COMPOSE + + formal = ToolContext(run_id="p2", node_id="look", run_class="formal") + with pytest.raises(ValueError) as caught: + await querycore.caliber_query(formal, workflow=asset["workflow_id"], card=CARD, + metric_ids=["gmv"], inputs=dict(INPUTS)) + assert publications.RECORD_MISSING in str(caught.value), "正式父 Run 用的是 publications.judge 的原码" + + record_id = await add_record(asset) + await confirm(asset, record_id) + await publish(client, asset) + proven = await querycore.caliber_query(ToolContext(run_id="p3", node_id="look", run_class="formal"), + workflow=asset["workflow_id"], card=CARD, metric_ids=["gmv"], + inputs=dict(INPUTS)) + assert proven["ok"] and proven["purpose"] == publications.PURPOSE_FORMAL + assert proven["publication"]["identity"] == publications.PROVEN + async with SessionLocal() as session: + child = await session.get(Run, proven["run_id"]) + assert child.origin["purpose"] == publications.PURPOSE_FORMAL and child.origin["parent_run_id"] == "p3" + + +async def test_the_actor_comes_from_the_parent_run_not_the_parameters(client): + """认证主体来自父 Run,工具参数里没有这一项,也传不了。""" + asset = await published(client) + run = await run_manager.start(graph=parent_graph(asset["workflow_id"]), input_payload={}, started_by="老王") + row = await settled(run.id) + assert row.status == "succeeded", row.error + child_id = (await tool_result(row.id))["run_id"] + async with SessionLocal() as session: + child = await session.get(Run, child_id) + assert child.started_by == "老王" + + +# ========================================================================== +# 6、协作成员路径:成员绑口径查询时,多查询逐条编号、逐条认工件 +# ========================================================================== + + +def team_graph(workflow_id: str) -> dict[str, Any]: + """协作团队:成员「查数」绑 caliber_query 与分析工具(绑了分析工具才编 Qn),另一个只是说话。""" + agents = [ + {"name": "查数", "description": "查口径", "system": "你会查口径", "max_steps": 1, + "tools": [querycore.CALIBER_QUERY, "analysis_comparable"]}, + {"name": "复核", "description": "复核别人算的数", "system": "你复核", "max_steps": 1, "tools": []}, + ] + return S.chain( + S.node("start", "input"), + S.node("team", "supervisor", goal="算一下销售额与最大单笔", agents=agents, max_rounds=2, max_parallel=1, + approval="never"), + S.node("out", "output", fields=[{"name": "答", "value": "{{ nodes.team.text }}"}]), + ) + + +async def test_a_cooperative_member_numbers_every_query_of_one_call(client): + """成员绑的口径查询交回两条查询:逐条编号、逐条进成员自己的分析容器,编号与执行身份记在调用记录里。 + + 协作节点不记证据台账时编号只给成员自己下钻用,所以编号要和这次调用的调用记录一起留下来;否则事后看不出 + 某个 Qn 是哪一次执行的哪条查询。给了 ledger 时(K10 收尾)同时逐条记一条运行台账的 query 条目。""" + from app.capabilities.registry import snapshot_owned + from app.engine.nodes import multi + from app.tools.analysis import AnalysisScope + + asset = await published(client) + parent = await run_parent(asset, metric_ids=["gmv", "peak"]) + payload = await tool_result(parent.id) + content = json.dumps(payload, ensure_ascii=False) + scope = AnalysisScope(node_id="team") + record: dict[str, Any] = {} + ledger: list[dict[str, Any]] = [] + + out = await multi._numbered(scope, querycore.CALIBER_QUERY, content, None, parent.id, "team", + call_id="call-1", member="查数", exec_no=1, record=record, ledger=ledger) + assert out.startswith("【证据 Q1、Q2】"), "一次交回多条查询:两条都要编号(以前只认第一条)" + assert list(scope.queries) == ["Q1", "Q2"] + traced = record["queries"] + assert [q["alias"] for q in traced] == ["Q1", "Q2"] + assert record["alias"] == "Q1" and record["artifact"] == payload["queries"][0]["artifact"] + assert [q["query_id"] for q in traced] == [q["query_id"] for q in payload["queries"]] + assert [q["artifact"] for q in traced] == [q["artifact"] for q in payload["queries"]] + # 执行身份照抄口径查询自己带着的那一份(K09 算好的):真的执行那次 SQL 的子运行、那条查询的第几次 + child = payload["run_id"] + assert all(q["execution_id"] == p["execution_id"] and child in q["execution_id"] + for q, p in zip(traced, payload["queries"])) + assert all(q["attempt"] == p["attempt"] >= 1 for q, p in zip(traced, payload["queries"])) + # 两条工件都是这次父运行(明确派生的子运行)落下的查询快照 + assert all([await snapshot_owned(q["artifact"], parent.id, querycore.CALIBER_QUERY) for q in traced]) + # 运行台账的条目:与 tools/llm 记的那一种同形,另带成员归属(node_id 前缀 + member) + assert [e["node_id"] for e in ledger] == ["team:查数", "team:查数"] + assert [e["member"] for e in ledger] == ["查数", "查数"] + assert [e["artifact"] for e in ledger] == [q["artifact"] for q in payload["queries"]] + assert all(e["kind"] == "query" and e["tool"] == querycore.CALIBER_QUERY and e["exec"] == 1 + and e["call_id"] == "call-1" for e in ledger) + assert all(e["source"] and e["columns"] and e["rows"] >= 1 and e["truncated"] is False for e in ledger) + assert [e["query_id"] for e in ledger] == [q["query_id"] for q in payload["queries"]] + assert [e["execution_id"] for e in ledger] == [q["execution_id"] for q in payload["queries"]] + assert all(e["origin"]["workflow_id"] == asset["workflow_id"] for e in ledger) + assert all(e["parameters"]["inputs_hash"] for e in ledger), "复算要的材料跟着条目走" + + +async def test_a_cooperative_member_refuses_forged_and_other_runs_artifacts(client): + """名字对了,工件也得对:伪造的、别的运行落的、不是查询快照的都不进成员的分析容器、也不进运行台账。""" + from app.engine.nodes import multi + from app.tools.analysis import AnalysisScope + + asset = await published(client) + parent = await run_parent(asset, metric_ids=["gmv", "peak"]) + payload = await tool_result(parent.id) + # 一份真的、一份工件 id 换掉的 + forged = json.loads(json.dumps(payload)) + forged["queries"][0]["artifact"] = "a" * 64 + content = json.dumps(forged, ensure_ascii=False) + scope = AnalysisScope(node_id="team") + record: dict[str, Any] = {} + ledger: list[dict[str, Any]] = [] + out = await multi._numbered(scope, querycore.CALIBER_QUERY, content, None, parent.id, "team", + call_id="call-1", member="查数", exec_no=1, record=record, ledger=ledger) + assert out == f"【证据 Q1】\n{content}", "只给认下来的那条编号" + assert list(scope.queries) == ["Q1"], "伪造的那条不进容器,真的那条照记" + assert [q["artifact"] for q in record["queries"]] == [payload["queries"][1]["artifact"]] + assert [e["artifact"] for e in ledger] == [payload["queries"][1]["artifact"]], "台账里也只记真的那条" + + # 同一份真工件,换一个运行 id:不是这次运行(也不是它派生的子运行)落的,整条都不认 + real = json.dumps(payload, ensure_ascii=False) + other = AnalysisScope(node_id="team") + other_record: dict[str, Any] = {} + other_ledger: list[dict[str, Any]] = [] + out = await multi._numbered(other, querycore.CALIBER_QUERY, real, None, "another-run", "team", + call_id="call-1", member="查数", exec_no=1, record=other_record, + ledger=other_ledger) + assert out == real and not other.queries and not other_record and not other_ledger + + +async def test_a_cooperative_member_keeps_the_single_query_behavior(): + """单条数据源查询照旧:一个 Qn、内容前面一行编号,执行身份按这次调用的 id 算(同 tools/registry)。""" + from app.engine.nodes import multi + from app.tools.analysis import AnalysisScope + + scope = AnalysisScope(node_id="team") + record: dict[str, Any] = {} + ledger: list[dict[str, Any]] = [] + payload = {"artifact": "b" * 64, "columns": ["gmv"], "rows": [[1.0]], "truncated": False, "source": "shop", + "sql": "SELECT 1"} + content = json.dumps(payload) + out = await multi._numbered(scope, "db_query__shop", content, None, "run-1", "team", + call_id="call-1", member="查数", exec_no=2, record=record, ledger=ledger) + assert out == f"【证据 Q1】\n{content}" and list(scope.queries) == ["Q1"] + assert [q["artifact"] for q in record["queries"]] == ["b" * 64] + assert record["queries"][0]["execution_id"] == "run-1:team#call-1" + assert record["queries"][0]["query_id"] == "team" + [entry] = ledger + assert entry["node_id"] == "team:查数" and entry["member"] == "查数" and entry["exec"] == 2 + assert entry["query_id"] == "team" and entry["attempt"] == 2 + assert entry["source"] == "shop" and entry["columns"] == ["gmv"] and entry["rows"] == 1 + + +async def test_a_plain_tool_result_leaves_no_ledger_behind(): + """不是平台执行的查询(普通工具、编造的同样的 JSON):容器、调用记录、台账都不动。""" + from app.engine.nodes import multi + from app.tools.analysis import AnalysisScope + + scope = AnalysisScope(node_id="team") + record: dict[str, Any] = {} + ledger: list[dict[str, Any]] = [] + content = json.dumps({"artifact": "c" * 64, "columns": ["x"], "rows": [[1]]}) + out = await multi._numbered(scope, "calculator", content, None, "run-1", "team", + call_id="call-1", member="查数", exec_no=1, record=record, ledger=ledger) + assert out == content and not scope.queries and not record and not ledger + + +async def test_the_team_member_path_records_the_queries_it_numbered(client, monkeypatch): + """走真的一次协作运行:成员绑口径查询,编号与执行身份随团队产出留下来,成员看到的是「【证据 Q1、Q2】」。""" + from app.providers import mock_model + + asset = await published(client) + args = {"workflow": asset["workflow_id"], "card": CARD, "metric_ids": ["gmv", "peak"], "inputs": dict(INPUTS)} + decisions = [ + {"assignments": [{"agent": "查数", "instruction": "算 gmv 与 peak"}], "done": False, "reason": "先查"}, + {"assignments": [], "done": True, "reason": "够了"}, + ] + turns = {"n": 0} + seen: list[str] = [] + + def _decide(self, messages): + seen.extend(str(m.content) for m in messages if isinstance(m, ToolMessage)) + if self.response_format: + i = turns["n"] + turns["n"] += 1 + return AIMessage(content=json.dumps(decisions[i] if i < len(decisions) else decisions[-1], + ensure_ascii=False)) + if self.tools and not any(isinstance(m, ToolMessage) for m in messages): + return AIMessage(content="查一下口径。", + tool_calls=[{"name": querycore.CALIBER_QUERY, "args": args, "id": "c1"}]) + return AIMessage(content="查完了:gmv 与 peak 都取到了。") + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", _decide) + run = await run_manager.start(graph=team_graph(asset["workflow_id"]), input_payload={}) + row = await settled(run.id) + assert row.status == "succeeded", row.error + assert any(text.startswith("【证据 Q1、Q2】") for text in seen), "成员拿到的结果前面要写全这一次的编号" + + from app.engine.evidence_reader import read_sealed + + team = (await read_sealed(row.id)).payload_of(["team"]) + assert isinstance(team, dict) + [record] = team["transcript"][0]["tool_calls"] + traced = record["queries"] + assert [q["alias"] for q in traced] == ["Q1", "Q2"] + assert {q["query_id"] for q in traced} == {f"{asset['workflow_id']}:sales", f"{asset['workflow_id']}:shared"} + # 执行身份指的是真的执行那次 SQL 的子运行;父子关系在子运行的来源里 + child_id = str(traced[0]["execution_id"]).split(":", 1)[0] + async with SessionLocal() as session: + child = await session.get(Run, child_id) + assert child is not None and (child.origin or {}).get("parent_run_id") == row.id + assert {str(q["execution_id"]).split(":", 1)[0] for q in traced} == {child_id}, "两条查询在同一次执行里" + assert [q["attempt"] for q in traced] == [1, 1] + + +#: 成员这一轮查的是另一个窗口:和上面调用工具节点那条的 SQL 不一样,两条的查询快照各是各的(好断言归属) +MEMBER_INPUTS = {"start": "2026-08-01", "end": "2026-12-01"} + + +def team_report_graph(workflow_id: str) -> dict[str, Any]: + """入口 → 调用工具(口径查询)→ 协作团队(成员也绑口径查询)→ 报告 → 出口。 + + 两处口径查询各交回两条 SQL,报告目录只收调用工具节点那两条:成员的查询是**附加**在封存证据上的。""" + agents = [ + {"name": "查数", "description": "查口径", "system": "你会查口径", "max_steps": 1, + "tools": [querycore.CALIBER_QUERY, "analysis_comparable"]}, + {"name": "复核", "description": "复核别人算的数", "system": "你复核", "max_steps": 1, "tools": []}, + ] + return S.chain( + S.node("start", "input"), + S.node("look", "tool", tool=querycore.CALIBER_QUERY, args={ + "workflow": workflow_id, "card": CARD, "metric_ids": ["gmv", "peak"], "inputs": dict(INPUTS)}), + S.node("team", "supervisor", goal="再按全年口径核一遍", agents=agents, max_rounds=2, max_parallel=1, + approval="never"), + S.node("write", "report", instructions="写一段说明"), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.write.text }}"}]), + ) + + +async def test_member_queries_join_the_sealed_evidence_without_renumbering_the_report(client, monkeypatch): + """成员查到的数进父 Run 的封存证据(带成员前缀、来源、执行身份的 query 条目),报告目录的全局 Q 编号一个字不变。 + + 报告目录按祖先收证据(report.report_catalog 的 allowed),成员条目的节点 id 是「协作节点 id:成员名」,既不像子工作流 + 转发的「协作节点 id/成员名」那样被 engine/compiler 的 _own_evidence 滤掉(那会让条目根本进不了封存),也不落在报告的 + 收证据范围里——成员查到的数是附加证据:封存读取(sealed.queries / query_records / entries)、导出包的来源与遮罩判断、 + 运行对比读得到,报告里的 Qn 还是原来那几条、面板按报告引用的那一份也不变。""" + from app.core import artifact_store + from app.engine.evidence_reader import read_sealed + from app.providers import mock_model + + asset = await published(client) + args = {"workflow": asset["workflow_id"], "card": CARD, "metric_ids": ["gmv", "peak"], + "inputs": dict(MEMBER_INPUTS)} + decisions = [ + {"assignments": [{"agent": "查数", "instruction": "按全年口径核一遍"}], "done": False, "reason": "先查"}, + {"assignments": [], "done": True, "reason": "够了"}, + ] + turns = {"n": 0} + + def _decide(self, messages): + if self.response_format: + i = turns["n"] + turns["n"] += 1 + return AIMessage(content=json.dumps(decisions[i] if i < len(decisions) else decisions[-1], + ensure_ascii=False)) + if self.tools and not any(isinstance(m, ToolMessage) for m in messages): + return AIMessage(content="查一下口径。", + tool_calls=[{"name": querycore.CALIBER_QUERY, "args": args, "id": "c1"}]) + return AIMessage(content="按全年口径核过一遍,与周口径口径一致。") + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", _decide) + run = await run_manager.start(graph=team_report_graph(asset["workflow_id"]), input_payload={}) + row = await settled(run.id) + assert row.status == "succeeded", row.error + + sealed = await read_sealed(row.id) + # 1) 调用工具节点那两条(tools.py 记的)与成员那两条(这次新加的)各是各的 + look = [e for e in await finished_evidence(row.id, "look") if e.get("kind") == "query"] + member = [e for e in await finished_evidence(row.id, "team") if e.get("kind") == "query"] + assert [e["member"] for e in member] == ["查数", "查数"], "一次调用两条查询,各记一条(不重复)" + assert {e["node_id"] for e in member} == {"team:查数"}, "条目带成员归属" + assert all(e["exec"] == 1 and e["call_id"] == "c1" and e["tool"] == querycore.CALIBER_QUERY for e in member) + assert all(e["source"] == S.CURRENT["source"] and e["columns"] and e["rows"] >= 1 + and e["truncated"] is False for e in member) + assert all(e["query_id"] and e["execution_id"] and e["attempt"] == 1 for e in member) + assert all(e["origin"]["workflow_id"] == asset["workflow_id"] and e["parameters"]["inputs_hash"] + for e in member), "复算要的出处与材料跟着条目走" + assert not ({e["artifact"] for e in member} & {e["artifact"] for e in look}), "两处查的是不同窗口,工件各是各的" + + # 2) 封存证据(证据面板、导出包从这里认):成员那两条在 sealed.queries / query_records / entries 里 + member_artifacts = {e["artifact"] for e in member} + assert member_artifacts <= set(sealed.queries) + assert all(sealed.queries[a]["tool"] == querycore.CALIBER_QUERY for a in member_artifacts) + records = sealed.query_records_of("team") + assert {r["execution_id"] for r in records} == {e["execution_id"] for e in member} + assert [e.get("member") for e in sealed.entries if e.get("artifact") in member_artifacts] == ["查数", "查数"] + + # 3) 报告目录的全局 Q 编号一个字不变:只有调用工具节点那两条,成员的查数不在目录里 + write = sealed.payload_of(["write"]) + doc = artifact_store.load(str(write["doc_artifact"])) + aliases = {a: e.get("artifact") for a, e in (doc.get("catalog") or {}).items() if e.get("kind") == "query"} + assert set(aliases) == {"Q1", "Q2"}, "成员的查询不重编报告里的编号" + assert set(aliases.values()) == {e["artifact"] for e in look} + assert not (member_artifacts & set(aliases.values())) + + # 4) 导出包(可验证报告)也把成员查到的快照算进这次运行的查询:以前成员那条路连工具快照都不落,只能看事件里的预览, + # 长一点的返回被截断就认不出来(打包时按「认不出」宁可多遮),来源也就认不出 + from app.bundle.build import _query_artifacts, _query_sources + + events = list(sealed.events) + assert member_artifacts <= set(_query_artifacts(events)) + assert all(_query_sources(events).get(a) == S.CURRENT["source"] for a in member_artifacts) + page = await client.get(f"/api/runs/{row.id}/bundle.html") + assert page.status_code == 200, page.text + + +async def test_a_member_without_queries_leaves_the_team_output_unchanged(client, monkeypatch): + """普通成员(没查库)的产出与以前一字不差:团队产出不带 evidence 键,transcript 里也不多东西。""" + from app.providers import mock_model + + asset = await published(client) + agents = [{"name": "撰稿", "description": "写一段话", "system": "你撰稿", "max_steps": 1, "tools": []}] + graph = S.chain( + S.node("start", "input"), + S.node("team", "supervisor", goal="写一句", agents=agents, max_rounds=1, max_parallel=1, approval="never"), + S.node("out", "output", fields=[{"name": "答", "value": "{{ nodes.team.text }}"}]), + ) + + turns = {"n": 0} + + def _decide(self, messages): + if self.response_format: + turns["n"] += 1 + decided = ({"assignments": [{"agent": "撰稿", "instruction": "写一句"}], "done": False, "reason": "派活"} + if turns["n"] == 1 else + {"assignments": [], "done": True, "reason": "够了"}) + return AIMessage(content=json.dumps(decided, ensure_ascii=False)) + return AIMessage(content="写好了。") + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", _decide) + run = await run_manager.start(graph=graph, input_payload={}) + row = await settled(run.id) + assert row.status == "succeeded", row.error + assert await finished_evidence(row.id, "team") == [], "成员没查库,一条台账条目都不记" + from app.engine.evidence_reader import read_sealed + + team = (await read_sealed(row.id)).payload_of(["team"]) + [entry] = team["transcript"] + assert set(entry) == {"round", "agent", "instruction", "text", "tool_calls", "duration_ms"}, entry + assert "queries" not in team # 团队产出里只有 transcript 那一条,没有别的证据键 + assert asset["workflow_id"] + + +async def test_a_member_without_an_analysis_tool_still_gets_its_queries_into_the_evidence(client, monkeypatch): + """成员只绑口径查询(没绑分析工具):交给成员的内容一个字不改(没有容器可放编号),查到的数照样进封存证据。""" + from app.engine.evidence_reader import read_sealed + from app.providers import mock_model + + asset = await published(client) + args = {"workflow": asset["workflow_id"], "card": CARD, "metric_ids": ["gmv", "peak"], + "inputs": dict(MEMBER_INPUTS)} + agents = [{"name": "查数", "description": "查口径", "system": "你会查口径", "max_steps": 1, + "tools": [querycore.CALIBER_QUERY]}, + {"name": "复核", "description": "复核别人算的数", "system": "你复核", "max_steps": 1, "tools": []}] + graph = S.chain( + S.node("start", "input"), + S.node("team", "supervisor", goal="算一下销售额", agents=agents, max_rounds=2, max_parallel=1, + approval="never"), + S.node("out", "output", fields=[{"name": "答", "value": "{{ nodes.team.text }}"}]), + ) + decisions = [ + {"assignments": [{"agent": "查数", "instruction": "算 gmv 与 peak"}], "done": False, "reason": "先查"}, + {"assignments": [], "done": True, "reason": "够了"}, + ] + turns = {"n": 0} + seen: list[str] = [] + + def _decide(self, messages): + seen.extend(str(m.content) for m in messages if isinstance(m, ToolMessage)) + if self.response_format: + i = turns["n"] + turns["n"] += 1 + return AIMessage(content=json.dumps(decisions[i] if i < len(decisions) else decisions[-1], + ensure_ascii=False)) + if self.tools and not any(isinstance(m, ToolMessage) for m in messages): + return AIMessage(content="查一下口径。", + tool_calls=[{"name": querycore.CALIBER_QUERY, "args": args, "id": "c1"}]) + return AIMessage(content="查完了。") + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", _decide) + run = await run_manager.start(graph=graph, input_payload={}) + row = await settled(run.id) + assert row.status == "succeeded", row.error + assert seen and all(not t.startswith("【证据") for t in seen), "没绑分析工具:交回成员的内容一个字不改" + + entries = [e for e in await finished_evidence(row.id, "team") if e.get("kind") == "query"] + assert len(entries) == 2 and {e["node_id"] for e in entries} == {"team:查数"} + assert all(e["member"] == "查数" and e["query_id"] and e["execution_id"] and e["attempt"] == 1 + for e in entries) + sealed = await read_sealed(row.id) + assert {e["artifact"] for e in entries} <= set(sealed.queries) + [record] = (sealed.payload_of(["team"]) or {}).get("transcript", [{}])[0].get("tool_calls") or [{}] + assert [q["artifact"] for q in record["queries"]] == [e["artifact"] for e in entries] + assert all("alias" not in q for q in record["queries"]), "没有容器就没有本节点内的编号" + + +# ========================================================================== +# 6、复核出来的三条:授权范围继承、逐次执行身份、发起时预解析口径的源 +# ========================================================================== + +#: 记录表的列(和 tests/test_records.py 同一个形状的假数据) +RECORD_COLUMNS = [{"name": "门店", "label": "门店", "type": "string", "required": True}, + {"name": "数量", "label": "报损数量", "type": "integer", "required": True}] +#: 记录表的行级范围认的一列:查全部、只看自己的、一行都不给 +RECORD_COUNT = "SELECT count(*) AS n FROM records" + + +def records_graph(source_name: str) -> dict[str, Any]: + """父 Run 的图:查这张记录表(固定的数据版本里带着它的高水位与行级范围)。""" + return S.chain( + S.node("start", "input"), + S.node("q", "tool", tool=f"db_query__{source_name}", args={"sql": RECORD_COUNT}), + S.node("out", "output", fields=[{"name": "n", "value": "{{ nodes.q }}"}]), + ) + + +async def records_source(name: str = "门店报损", *, grants: dict[str, str] | None = None) -> tuple[str, str]: + """建一张记录表:所属应用 + 逐人的授权。返回 (源 id, 源名)。grants 缺省是给 uma 的一档 use。""" + from app.db.models import DataSource + from app.db.models_apps import App, AppGrant + from app.records.tables import ensure_table + + async with SessionLocal() as session: + app = App(name=f"{name}-{uuid.uuid4().hex[:6]}", created_by="建立人") + session.add(app) + await session.flush() + for who, role in ({"uma": "use"} if grants is None else grants).items(): + session.add(AppGrant(app_id=app.id, principal_kind="user", principal=who, role=role)) + table = await ensure_table(session, app, RECORD_COLUMNS) + await session.commit() + source = await session.get(DataSource, table.source_id) + # 一行 uma 提交的记录:行级范围是 all / mine 时看得见这一行,none 看不见 + store.append(path_of(table), columns_of(table), {"门店": "一店", "数量": 1}, version=table.version, + run_id=None, actor="uma", action_key=uuid.uuid4().hex) + return source.id, source.name + + +async def grant_caliber(workflow_id: str, version: int, who: str, role: str) -> str: + """给这个人在**这一版口径**上的资产授权:一份应用(当前发布版精确固定着这一版)+ 一条 AppGrant。返回应用 id。 + + 普通使用者按口径取数靠的就是它(apps/access.usable_calibers / caliber_role,K14):没有这一份,QueryCore 在起 Run + 之前就拒(querycore_not_authorized),工具那一层也拿不到数——记录表的行级授权(records_source 的 grants)不管口径。""" + from app.db.models_apps import App, AppGrant, AppVersion + + async with SessionLocal() as session: + app = App(name=f"口径授权-{uuid.uuid4().hex[:6]}", status="active", published_version=1) + session.add(app) + await session.flush() + session.add(AppVersion(app_id=app.id, version=1, spec={}, spec_hash="grant", + pins=[{"alias": "cal", "workflow_id": workflow_id, "version": int(version)}])) + session.add(AppGrant(app_id=app.id, principal_kind="user", principal=who, role=role)) + await session.commit() + return app.id + + +async def wait_for(run_id: str, statuses: tuple[str, ...], timeout: float = 30.0) -> Run: + """等运行到这几个状态之一(settled 把 interrupted 也当终态,审批那一段要另等)。""" + deadline = asyncio.get_running_loop().time() + timeout + while asyncio.get_running_loop().time() < deadline: + async with SessionLocal() as session: + row = await session.get(Run, run_id) + if row is not None and row.status in statuses: + return row + await asyncio.sleep(0.05) + raise AssertionError(f"运行 {run_id} 没有进入 {statuses}") + + +async def test_inherit_scope_keeps_the_parents_authorized_rows(): + """继承父 Run 的 data_versions:记录表的行级范围原样带着(all/mine/none 都不动),缺 rows 的按最窄的算。""" + from app.records.views import inherit_scope + + versions = { + "a": {"name": "甲", "origin": "records", "table": "t", "version": 1, "seq": 3, "rows": "all"}, + "b": {"name": "乙", "origin": "records", "table": "t", "version": 1, "seq": 4, "rows": "mine", + "viewer": "uma"}, + "c": {"name": "丙", "origin": "records", "table": "t", "version": 1, "seq": 5, "rows": "none"}, + "d": {"name": "丁", "origin": "records", "table": "t", "version": 1, "seq": 6}, # 老运行:没有范围 + "e": {"snapshot": "s1", "name": "上传表格"}, # 不是记录表 + } + inherit_scope(versions) + assert versions["a"]["rows"] == "all" + assert versions["b"]["rows"] == "mine" and versions["b"]["viewer"] == "uma" + assert versions["c"]["rows"] == "none" + assert versions["d"]["rows"] == "none", "没有范围的老项按最窄的算,绝不当成 all" + assert versions["e"] == {"snapshot": "s1", "name": "上传表格"}, "上传源不碰" + + +async def test_a_derived_child_inherits_the_parents_authorized_scope(client): + """正式父 Run 的行级范围是 all;派生的子运行是 exploratory,也不能按发起人重算成 mine。""" + from app.engine.runner import _data_versions # noqa: F401 + from tests.fakes import auth_env + + await auth_env.turn_on_local() + try: + await auth_env.make_user("uma", "user") + source_id, name = await records_source() + graph = records_graph(name) + # 父 Run:正式运行 → 看全部 + parent = await run_manager.start(graph=graph, input_payload={}, run_class="formal", started_by="uma") + parent = await settled(parent.id) + assert parent.status == "succeeded", parent.error + assert parent.data_versions[source_id]["rows"] == "all" + # 反例:同一个起点自己发起(不继承父 Run)→ 按发起人的 use 档收成 mine。没有这一条,上面那句断言说明不了什么 + own = await settled((await run_manager.start(graph=graph, input_payload={}, run_class="exploratory", + started_by="uma")).id) + assert own.data_versions[source_id]["rows"] == "mine" + assert own.data_versions[source_id]["viewer"] == "uma" + # 反例(同一条规则直接跑一遍):拿父 Run 那一份按子运行的类别与发起人重算,all 会收成 mine + from app.records.views import scope_entries + + recomputed = copy.deepcopy(parent.data_versions) + async with SessionLocal() as session: + await scope_entries(session, recomputed, run_class="exploratory", started_by="uma") + assert recomputed[source_id]["rows"] == "mine" + # 派生:照父 Run 那一份原样,不收窄、也不添 viewer + child = await settled((await run_manager.start(graph=graph, input_payload={}, run_class="exploratory", + started_by="uma", data_versions=parent.data_versions)).id) + assert child.status == "succeeded", child.error + assert child.data_versions[source_id]["rows"] == "all", "父已授权 all,子运行不能收成 mine" + assert "viewer" not in child.data_versions[source_id] + assert child.data_versions[source_id]["seq"] == parent.data_versions[source_id]["seq"] + finally: + await auth_env.reset() + + +async def test_a_compose_parent_keeps_its_scope_after_the_user_is_disabled(client): + """发起之后人停用了:同一次运行(派生出来的那一段)仍按发起时定下的那一档看,不改判成 none。""" + from app.db.models import User + from tests.fakes import auth_env + + await auth_env.turn_on_local() + try: + await auth_env.make_user("uma", "user") + source_id, name = await records_source() + graph = records_graph(name) + parent = await settled((await run_manager.start(graph=graph, input_payload={}, started_by="uma")).id) + assert parent.data_versions[source_id]["rows"] == "mine" + async with SessionLocal() as session: + user = (await session.execute(select(User).where(User.username == "uma"))).scalar_one() + user.disabled = True + await session.commit() + # 现在自己发起一次:人不在(停用)→ 一行都不给 + fresh = await settled((await run_manager.start(graph=graph, input_payload={}, started_by="uma")).id) + assert fresh.data_versions[source_id]["rows"] == "none" + # 派生:照父 Run 那一份(mine + 看的人),不因为人后来停用而改判 + child = await settled((await run_manager.start(graph=graph, input_payload={}, run_class="exploratory", + started_by="uma", data_versions=parent.data_versions)).id) + assert child.data_versions[source_id]["rows"] == "mine" + assert child.data_versions[source_id]["viewer"] == "uma" + finally: + await auth_env.reset() + + +# ---- 2) 同一份工件对应两条不同的逻辑查询 ---------------------------------- + + +def same_duration(monkeypatch) -> None: + """把每条查询的耗时记成 0:同一条 SQL、同一批数据、同一份参数的两条查询就得到**同一个**工件(内容寻址)。 + + 耗时是快照内容的一部分(每条查询各记各的、几毫秒上下的抖动):这一条测的是「同一份工件对应两条不同的逻辑查询」 + 时证据索引的取法,所以先把那个抖动按平,让两份内容真的逐字相同。""" + import dataclasses + + from app.tools import datasource + + real = datasource.run_query + + async def zeroed(source: Any, sql: str, **kw: Any) -> Any: + return dataclasses.replace(await real(source, sql, **kw), elapsed_ms=0) + + monkeypatch.setattr(datasource, "run_query", zeroed) + + +async def test_two_logical_queries_sharing_one_artifact_are_both_reported(client, monkeypatch): + """两个取数节点写同一条 SQL、读同一批数据:内容寻址下是**同一个**工件,但它们是两条不同的逻辑查询。 + + 按工件 id 去重的证据索引会把它们并成一条,早先那条就找不到自己那一次——所以逐次记下的执行身份才是取法。""" + same_duration(monkeypatch) + asset = await make_workflow(graph=twin_graph()) + await publish(client, asset) + outcome = await run_once(asset, metric_ids=["left", "right"], inputs=dict(INPUTS)) + assert outcome.ok, [p["code"] for p in outcome.problems] + data = outcome.as_dict() + assert [q["query_id"] for q in data["queries"]] == [f"{asset['workflow_id']}:one", + f"{asset['workflow_id']}:two"] + assert all(q["found"] for q in data["queries"]) + assert len({q["artifact"] for q in data["queries"]}) == 1, "同一条 SQL 同一批数据 → 同一个工件" + assert len({q["execution_id"] for q in data["queries"]}) == 2, "两条逻辑查询各有各的执行身份" + assert all(q["row_count"] == 1 and q["columns"] for q in data["queries"]) + assert {m["id"]: m["value"] for m in outcome.metrics} == {"left": WINDOW_SUM, "right": WINDOW_SUM} + + +async def test_a_later_execution_of_the_same_sql_takes_its_own_record(client): + """同一个节点执行两次(同一条 SQL、同一份数据、同一个工件):引用取**最后一次**那次执行的身份。""" + from app.engine.evidence_reader import read_sealed + + asset = await published(client) + outcome = await run_once(asset, metric_ids=["gmv"], inputs=dict(INPUTS)) + assert outcome.ok + sealed = await read_sealed(outcome.run_id) + records = sealed.query_records_of("sales") + assert len(records) == 1 and records[-1]["artifact"] == outcome.queries[0]["artifact"] + # 逐次记录与按工件去重的那一份指向同一次执行(认法不同、结论一致) + assert sealed.queries[records[-1]["artifact"]]["exec"] == records[-1]["exec"] + assert querycore._query_record_of(sealed, "sales")["execution_id"] == records[-1]["execution_id"] + # 没有这个节点的逐次记录时(老运行、只回了 tool.end)退回按工件去重的那一份 + assert querycore._query_record_of(sealed, "shared") is None + + +# ---- 3) 父 Run 发起时预解析口径那一版读的源 ------------------------------- + + +def book(sheets: dict[str, list[list]]) -> bytes: + import io + + from openpyxl import Workbook + + wb = Workbook() + wb.remove(wb.active) + for title, rows in sheets.items(): + ws = wb.create_sheet(title) + for row in rows: + ws.append(row) + buf = io.BytesIO() + wb.save(buf) + return buf.getvalue() + + +#: 上传表格第一版:数量合计 3;第二版(重传):合计 100,另多一张表 +UP_V1 = {"明细": [["区域", "数量"], ["分区甲", 1], ["分区乙", 2]]} +UP_V2 = {"明细": [["区域", "数量"], ["分区甲", 60], ["分区乙", 40]], "新增": [["时段", "客流"], ["上午", 7]]} + + +async def upload_source(sheets: dict[str, list[list]], *, name: str | None = None) -> tuple[str, str, str]: + """发布一版上传表格,返回 (源 id, 快照 id, 源名)。给了 name 就是**往同一个源上重传**(新的一版)。""" + from app.data import table_versions + + name = name or f"up_{uuid.uuid4().hex[:8]}" + async with SessionLocal() as session: + row = (await session.execute(select(DataSource).where(DataSource.name == name))).scalar_one_or_none() + if row is None: + row = DataSource(name=name, kind="sqlite", readonly=True, origin="upload", enabled=True) + session.add(row) + result = await table_versions.publish_upload(session, row, book(sheets), "客流.xlsx", + header_row=1, mixed="reject", raw_mode=False) + return row.id, result.snapshot_id, name + + +def upload_caliber_graph(source_name: str) -> dict[str, Any]: + """口径的取数节点查这张上传表格(国产表名照原样写在 SQL 里)。""" + return S.chain( + S.node("start", "input"), + S.node("fetch", "tool", tool=f"db_query__{source_name}", + args={"sql": 'SELECT SUM("数量") AS total FROM "明细"'}), + S.node(CARD, "metrics", caliber="上传合计", caliber_version="v1", + metrics=[{"id": "total", "name": "合计", "unit": "件", + "expression": "cell(nodes.fetch, 0, 'total')"}]), + S.node("write", "report", instructions="写周销售"), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.write.text }}"}]), + ) + + +async def test_the_parent_pins_the_sources_its_caliber_reads(client): + """绑了 caliber_query 的节点读的**不在本图里**:口径那一版图里的源也要在父 Run 发起时固定下来。""" + from app.engine.schema import GraphSpec + from app.engine.runner import _data_versions + + other_id, _, _ = await upload_source(UP_V1) # 别的源:不许被顺手固定 + source_id, snap1, name = await upload_source(UP_V1) + asset = await make_workflow(graph=upload_caliber_graph(name)) + await publish(client, asset) + graph = parent_graph(asset["workflow_id"], metric_ids=["total"], inputs={}) + async with SessionLocal() as session: + pins = await _data_versions(session, GraphSpec.model_validate(graph)) + assert pins[source_id]["snapshot"] == snap1, "口径那一版的取数源要在父 Run 发起时就固定" + assert pins[source_id]["name"] == name + assert other_id not in pins, "没用到的源照旧不固定" + # 认不到工作流(名字写错了):这一次调用会被 QueryCore 拒,一条数据都不读——不必把全部源都固定上 + broken = parent_graph("nope-not-a-workflow", metric_ids=["total"], inputs={}) + async with SessionLocal() as session: + assert await _data_versions(session, GraphSpec.model_validate(broken)) == {} + + +async def test_an_agent_or_templated_caliber_reference_pins_every_source(client): + """口径是 Agent 挑的、或者写的是模板:发起时说不准读哪个源,把启用的上传源全部固定上。""" + from app.engine.schema import GraphSpec + from app.engine.runner import _data_versions + + source_id, snap1, _ = await upload_source(UP_V1) + agent_graph = S.chain( + S.node("start", "input"), + S.node("bot", "agent", prompt="算一下", tools=[querycore.CALIBER_QUERY], approval="never"), + S.node("out", "output", fields=[{"name": "答", "value": "{{ nodes.bot.text }}"}]), + ) + async with SessionLocal() as session: + pins = await _data_versions(session, GraphSpec.model_validate(agent_graph)) + assert pins.get(source_id, {}).get("snapshot") == snap1 + templated = S.chain( + S.node("start", "input"), + S.node("look", "tool", tool=querycore.CALIBER_QUERY, args={ + "workflow": "{{ vars.w }}", "card": CARD, "metric_ids": ["total"], "inputs": {}}), + S.node("out", "output", fields=[{"name": "答", "value": "{{ nodes.look.ok }}"}]), + ) + async with SessionLocal() as session: + pins = await _data_versions(session, GraphSpec.model_validate(templated)) + assert pins.get(source_id, {}).get("snapshot") == snap1 + + +async def test_a_reupload_after_launch_still_reads_the_pinned_version(client): + """父 Run 发起之后重传:这次运行里口径读的还是发起时那一版(run.started 里记的就是它)。""" + source_id, s1, name = await upload_source(UP_V1) + asset = await make_workflow(graph=upload_caliber_graph(name)) + await publish(client, asset) + graph = parent_graph(asset["workflow_id"], metric_ids=["total"], inputs={}, gate=True) + run = await run_manager.start(graph=graph, input_payload={}) + assert (await wait_for(run.id, ("interrupted",))).status == "interrupted" + + _, s2, _ = await upload_source(UP_V2, name=name) # 停在确认上时重传:当前版本换成合计 100 的那一版 + assert s2 != s1 + await run_manager.resume(run.id, {"approved": True}) + done = await settled(run.id) + assert done.status == "succeeded", done.error + + assert done.data_versions[source_id]["snapshot"] == s1 + started = await events_of(run.id, "run.started") + assert all(e["data_versions"][source_id]["snapshot"] == s1 for e in started), "run.started 里可见实际固定的版本" + tool = await tool_result(done.id) + assert tool["ok"], tool.get("problems") + assert tool["metrics"][0]["value"] == 3, "重传之后这次运行读的还是发起时那一版" + assert tool["data"]["data_versions"] == {name: s1} + + +async def test_two_calls_in_one_parent_run_read_the_same_version(client): + """父 Run 的两次调用(中间重传过)读的还是同一版:不是各自在子运行里补固定当前版本。""" + source_id, s1, name = await upload_source(UP_V1) + asset = await make_workflow(graph=upload_caliber_graph(name)) + await publish(client, asset) + args = {"workflow": asset["workflow_id"], "card": CARD, "metric_ids": ["total"], "inputs": {}} + graph = S.chain( + S.node("start", "input"), + S.node("one", "tool", tool=querycore.CALIBER_QUERY, args=dict(args)), + S.node("gate", "human", mode="approve", title="看一眼"), + S.node("two", "tool", tool=querycore.CALIBER_QUERY, args=dict(args)), + S.node("out", "output", fields=[{"name": "答", "value": "{{ nodes.two.ok }}"}]), + ) + run = await run_manager.start(graph=graph, input_payload={}) + assert (await wait_for(run.id, ("interrupted",))).status == "interrupted" + + _, s2, _ = await upload_source(UP_V2, name=name) # 第一次调用之后重传(同一个源的新一版) + assert s2 != s1 + await run_manager.resume(run.id, {"approved": True}) + done = await settled(run.id) + assert done.status == "succeeded", done.error + + first, second = await tool_result(done.id, "one"), await tool_result(done.id, "two") + assert first["ok"] and second["ok"], (first.get("problems"), second.get("problems")) + assert first["metrics"][0]["value"] == 3 and second["metrics"][0]["value"] == 3, \ + "同一次运行里的两次调用要读同一版数据" + assert done.data_versions[source_id]["snapshot"] == s1 + for result in (first, second): + async with SessionLocal() as session: + child = await session.get(Run, result["run_id"]) + assert child.data_versions[source_id]["snapshot"] == s1, "子运行照父 Run 固定的那一版,不各自补固定" + + +# ========================================================================== +# 7、晚解析的源固定在**父 Run** 上(发布得晚 / 推荐版变了 / 动态引用) +# ========================================================================== + + +def records_caliber_graph(source_name: str) -> dict[str, Any]: + """口径的取数节点查这张记录表(读哪些行由这次运行定下的行级范围决定)。""" + return S.chain( + S.node("start", "input"), + S.node("fetch", "tool", tool=f"db_query__{source_name}", args={"sql": RECORD_COUNT}), + S.node(CARD, "metrics", caliber="记录合计", caliber_version="v1", + metrics=[{"id": "n", "name": "条数", "unit": "条", + "expression": "cell(nodes.fetch, 0, 'n')"}]), + S.node("write", "report", instructions="写周销售"), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.write.text }}"}]), + ) + + +def gated_parent_graph(workflow_id: str, *, metric_ids: list[str], card: str = CARD, + calls: tuple[str, ...] = ("look",)) -> dict[str, Any]: + """父 Run 的图:入口 → 人工确认 →(一到两处)调用工具(caliber_query)→ 出口。 + + 审批挡在调用之前:测试要在「发起」与「第一次调用」之间做事(发布口径、重传、换推荐版)。""" + parts = [S.node("start", "input"), S.node("gate", "human", mode="approve", title="看一眼")] + for name in calls: + parts.append(S.node(name, "tool", tool=querycore.CALIBER_QUERY, args={ + "workflow": workflow_id, "card": card, "metric_ids": metric_ids, "inputs": {}})) + parts.append(S.node("out", "output", fields=[{"name": "答", "value": "运行结束"}])) + return S.chain(*parts) + + +async def pin_events(run_id: str) -> list[dict[str, Any]]: + """这次运行里补固定数据版本的那些事件(tools/datasource.LATE_PIN_CODE)。""" + from app.tools.datasource import LATE_PIN_CODE + + return [e for e in await events_of(run_id, "log") if e.get("code") == LATE_PIN_CODE] + + +@pytest.mark.parametrize("run_class, grant, rows, viewer", [ + ("formal", "use", "all", None), # 正式父 Run:看全部 + ("exploratory", "use", "mine", "uma"), # 交互:use 档只看自己的 + ("exploratory", "observe", "all", None), # 交互:observe 档看全部 + ("exploratory", None, "none", None), # 交互:没有口径授权,这一次调用在起 Run 之前就被拒 +]) +async def test_a_caliber_published_after_launch_is_pinned_on_the_parent(client, run_class, grant, rows, viewer): + """新发布:口径在父 Run 发起时还没有推荐版(发起时算不到),第一次调用时按**父 Run 的**类别与授权补固定。 + + 固定记在父 Run 上、追加一条补固定事件(run.started 已经落库),子运行照父 Run 那一份继承——不能落到子运行里 + 按 exploratory 重算(那会把正式父 Run 的 all 收成 mine/none)。 + + exploratory 这一档(普通使用者按口径取数)另有一道 K14 的资产授权:发布之后另给 uma 一份与这里那一档相同的授权 + (grant_caliber);**没有**口径授权的那一档调用在起 Run 之前就被拒,一行都不读、也不补固定。""" + from app.engine.runner import _data_versions + from app.engine.schema import GraphSpec + from tests.fakes import auth_env + + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("uma", "user") + source_id, name = await records_source(grants={} if grant is None else {"uma": grant}) + asset = await make_workflow(graph=records_caliber_graph(name)) # 建了,但**还没发布** + graph = gated_parent_graph(asset["workflow_id"], metric_ids=["n"]) + async with SessionLocal() as session: + assert await _data_versions(session, GraphSpec.model_validate(graph)) == {}, "还没发布:发起时算不到" + run = await run_manager.start(graph=graph, input_payload={}, run_class=run_class, started_by="uma") + assert (await wait_for(run.id, ("interrupted",))).status == "interrupted" + + if run_class == "formal": # 正式父 Run 走 formal judge:依据要齐 + await confirm(asset, await add_record(asset, metric_ids=("n",))) + await publish(admin, asset) # 停在确认上时发布:推荐版出现了 + if grant is not None: + await grant_caliber(asset["workflow_id"], 1, "uma", grant) + await run_manager.resume(run.id, {"approved": True}) + done = await settled(run.id) + if grant is None: + assert done.status == "failed" and querycore.NOT_AUTHORIZED in str(done.error or ""), done.error + assert source_id not in (done.data_versions or {}), "被拒的这一次没有固定任何数据版本" + assert await pin_events(done.id) == [], "被拒的这一次连一条补固定事件都不该有" + return + assert done.status == "succeeded", done.error + + entry = done.data_versions[source_id] + assert entry["rows"] == rows, "行级范围取父 Run 已授权的那一档,不按子运行的类别重算" + assert entry.get("viewer") == viewer + assert entry["late"] is True and entry["caliber"] == f"{asset['workflow_id']}@1:{CARD}" + events = await pin_events(done.id) + assert len(events) == 1 and events[0]["source"] == name and events[0]["rows"] == rows + assert events[0]["caliber"] == f"{asset['workflow_id']}@1:{CARD}" and events[0]["late"] is True + # 子运行照父 Run 那一份继承:不是它自己按 exploratory 另算一份 + tool = await tool_result(done.id) + assert tool["ok"], tool.get("problems") + async with SessionLocal() as session: + child = await session.get(Run, tool["run_id"]) + assert child.data_versions[source_id]["rows"] == rows + assert child.data_versions[source_id]["caliber"] == f"{asset['workflow_id']}@1:{CARD}" + assert tool["metrics"][0]["value"] == (1 if rows != "none" else 0) + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_later_calls_reuse_the_first_pin(client): + """同父 Run 的两次调用:第一次把源固定在父 Run 上,第二次照旧复用那一版,不重新固定、不再补一条事件。""" + from app.engine.runner import _data_versions + from app.engine.schema import GraphSpec + from tests.fakes import auth_env + + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("uma", "user") + source_id, _ = await records_source() + asset = await make_workflow(graph=records_caliber_graph(await _records_name(source_id))) + graph = gated_parent_graph(asset["workflow_id"], metric_ids=["n"], calls=("one", "two")) + async with SessionLocal() as session: + assert await _data_versions(session, GraphSpec.model_validate(graph)) == {} + run = await run_manager.start(graph=graph, input_payload={}, run_class="formal", started_by="uma") + assert (await wait_for(run.id, ("interrupted",))).status == "interrupted" + await confirm(asset, await add_record(asset, metric_ids=("n",))) # 正式父 Run:依据要齐 + await publish(admin, asset) + # 正式运行也要这一版口径的资产授权(K14):发布之后按同一档补上 + await grant_caliber(asset["workflow_id"], 1, "uma", "use") + await run_manager.resume(run.id, {"approved": True}) + done = await settled(run.id) + assert done.status == "succeeded", done.error + + entry = done.data_versions[source_id] + assert entry["rows"] == "all" and entry["late"] is True + assert len(await pin_events(done.id)) == 1, "两次调用只补固定一次:后面那次复用第一版" + first, second = await tool_result(done.id, "one"), await tool_result(done.id, "two") + assert first["ok"] and second["ok"], (first.get("problems"), second.get("problems")) + assert first["data"]["data_versions"] == second["data"]["data_versions"] + for tool in (first, second): + async with SessionLocal() as session: + child = await session.get(Run, tool["run_id"]) + assert child.data_versions[source_id]["seq"] == entry["seq"] + assert child.data_versions[source_id]["rows"] == "all" + finally: + await admin.aclose() + await auth_env.reset() + + +async def _records_name(source_id: str) -> str: + async with SessionLocal() as session: + return str((await session.get(DataSource, source_id)).name) + + +async def test_a_new_recommended_version_with_a_moved_source_is_refused(client): + """审批期间推荐版换了一版、源也重传了:这一次要执行的口径引用的是另一版——明确说冲突,不静默跨版。""" + source_id, s1, name = await upload_source(UP_V1) + asset = await make_workflow(graph=upload_caliber_graph(name)) + await publish(client, asset) # v1 是推荐版 + graph = gated_parent_graph(asset["workflow_id"], metric_ids=["total"]) + run = await run_manager.start(graph=graph, input_payload={}) + row = await wait_for(run.id, ("interrupted",)) + assert row.status == "interrupted" + assert row.data_versions[source_id]["snapshot"] == s1 # 发起时固定在这一版 + assert row.data_versions[source_id]["caliber"] == f"{asset['workflow_id']}@1:{CARD}" + + _, s2, _ = await upload_source(UP_V2, name=name) # 重传:当前版本换成合计 100 的那一版 + changed = upload_caliber_graph(name) + next(metrics for metrics in changed["nodes"] if metrics["id"] == CARD)["data"]["config"]["metrics"][0]["label"] = "合计2" + asset = await add_version(asset, changed, version=2) + await publish(client, asset, version=2) # 推荐版换成 v2(引用的是重传后的那一版) + await run_manager.resume(run.id, {"approved": True}) + done = await settled(run.id) + + assert done.status == "failed", done.error + error = done.error or "" + assert querycore.DATA_VERSION_CONFLICT in error, error + assert name in error and s1[:12] in error and s2[:12] in error, error + async with SessionLocal() as session: + children = (await session.execute(select(Run).where(Run.origin.is_not(None)))).scalars().all() + assert [c for c in children if (c.origin or {}).get("parent_run_id") == done.id] == [], "冲突就不发起子运行" + + +async def test_two_calls_after_a_late_pin_read_the_same_version(client): + """新发布的口径:第一次调用把源固定在父 Run 上,两次调用之间重传,第二次读的还是那一版(同一次运行不跨版)。""" + source_id, s1, name = await upload_source(UP_V1) + asset = await make_workflow(graph=upload_caliber_graph(name)) # 还没发布 + args = {"workflow": asset["workflow_id"], "card": CARD, "metric_ids": ["total"], "inputs": {}} + graph = S.chain( + S.node("start", "input"), + S.node("gate1", "human", mode="approve", title="看一眼"), + S.node("one", "tool", tool=querycore.CALIBER_QUERY, args=dict(args)), + S.node("gate2", "human", mode="approve", title="再确认"), + S.node("two", "tool", tool=querycore.CALIBER_QUERY, args=dict(args)), + S.node("out", "output", fields=[{"name": "答", "value": "结束"}]), + ) + run = await run_manager.start(graph=graph, input_payload={}) + assert (await wait_for(run.id, ("interrupted",))).status == "interrupted" + + await publish(client, asset) # 新发布:发起时算不到 + await run_manager.resume(run.id, {"approved": True}) + assert (await wait_for(run.id, ("interrupted",))).status == "interrupted" + + _, s2, _ = await upload_source(UP_V2, name=name) # 两次调用之间重传 + assert s2 != s1 + await run_manager.resume(run.id, {"approved": True}) + done = await settled(run.id) + assert done.status == "succeeded", done.error + + assert done.data_versions[source_id]["snapshot"] == s1 + assert len(await pin_events(done.id)) == 1, "第一次调用补固定一次,第二次复用" + first, second = await tool_result(done.id, "one"), await tool_result(done.id, "two") + assert first["ok"] and second["ok"], (first.get("problems"), second.get("problems")) + assert [first["metrics"][0]["value"], second["metrics"][0]["value"]] == [3, 3], \ + "同一次运行里的两次调用读同一版数据" diff --git a/backend/tests/test_caliber_regressions.py b/backend/tests/test_caliber_regressions.py index 221cd910..ba402199 100644 --- a/backend/tests/test_caliber_regressions.py +++ b/backend/tests/test_caliber_regressions.py @@ -65,7 +65,8 @@ async def test_draft_edit_preserves_published_snapshot_and_updates_canvas(client _, before = await snapshots(wid) metrics = copy.deepcopy(body["metrics"]) metrics[0]["expression"] += " * 100" - changed = await client.patch(f"/api/ledger/drafts/{did}", json={"metrics": metrics}) + changed = await client.patch(f"/api/ledger/drafts/{did}", + json={"metrics": metrics, "expected_revision": body["revision"]}) assert changed.status_code == 200, changed.text workflow, after = await snapshots(wid) assert [v.version for v in after] == [1, 2] @@ -82,7 +83,8 @@ async def test_trial_is_invalidated_by_edit_and_late_results_cannot_replace_new_ did = body["id"] metrics = copy.deepcopy(body["metrics"]) metrics[0]["expression"] += " * 100" - changed = (await client.patch(f"/api/ledger/drafts/{did}", json={"metrics": metrics})).json() + changed = (await client.patch(f"/api/ledger/drafts/{did}", + json={"metrics": metrics, "expected_revision": body["revision"]})).json() assert changed["trial"]["status"] == "stale" assert not next(c for c in changed["checks"] if c["key"] == "trial")["ok"] old = (await client.get(f"/api/ledger/drafts/{did}/trial")).json() @@ -117,11 +119,13 @@ async def test_metric_edits_preserve_canvas_sql_and_node_ids(client, documents, graph = copy.deepcopy(workflow.graph) cfg(graph, "fetch_2")["args"]["sql"] = "SELECT SUM(amount) * 2 AS gmv FROM orders" cfg(graph, "start")["fields"].append({"name": "region", "type": "string", "required": True}) - saved = await client.patch(f"/api/workflows/{wid}", json={"graph": graph}) + saved = await client.patch(f"/api/workflows/{wid}", + json={"graph": graph, "expected_revision": workflow.version}) assert saved.status_code == 200, saved.text kept = copy.deepcopy(body["metrics"][1]) kept["name"] = "编辑第二组" - patched = await client.patch(f"/api/ledger/drafts/{did}", json={"metrics": [kept]}) + patched = await client.patch(f"/api/ledger/drafts/{did}", + json={"metrics": [kept], "expected_revision": saved.json()["version"]}) assert patched.status_code == 200, patched.text workflow, versions = await snapshots(wid) latest = versions[-1].graph @@ -131,7 +135,8 @@ async def test_metric_edits_preserve_canvas_sql_and_node_ids(client, documents, assert cfg(latest, "card")["metrics"][0]["expression"] == kept["expression"] assert validate_graph(GraphSpec.model_validate(latest)).ok assert cfg(latest, "out")["contract"]["required"] == [kept["id"]] - empty = await client.patch(f"/api/ledger/drafts/{did}", json={"metrics": []}) + empty = await client.patch(f"/api/ledger/drafts/{did}", + json={"metrics": [], "expected_revision": patched.json()["revision"]}) assert empty.status_code == 200 and empty.json()["metrics"] == [], empty.text @@ -141,7 +146,8 @@ async def test_draft_list_counts_current_canvas_metrics(client, documents, datas graph = copy.deepcopy(workflow.graph) metrics = cfg(graph, "card")["metrics"] metrics.append({**metrics[0], "id": "m2", "name": "另一个指标"}) - saved = await client.patch(f"/api/workflows/{workflow.id}", json={"graph": graph}) + saved = await client.patch(f"/api/workflows/{workflow.id}", + json={"graph": graph, "expected_revision": workflow.version}) assert saved.status_code == 200 items = (await client.get("/api/ledger/drafts")).json()["drafts"] assert next(item for item in items if item["id"] == body["id"])["metric_count"] == 2 @@ -239,7 +245,8 @@ async def test_real_trial_runs_current_canvas_version(client, documents, datasou workflow, _ = await snapshots(body["workflow_id"]) graph = copy.deepcopy(workflow.graph) cfg(graph, "card")["metrics"][0]["expression"] += " * 100" - saved = await client.patch("/api/workflows/" + body["workflow_id"], json={"graph": graph}) + saved = await client.patch("/api/workflows/" + body["workflow_id"], + json={"graph": graph, "expected_revision": workflow.version}) assert saved.status_code == 200 and saved.json()["version"] == 2, saved.text monkeypatch.setattr(api_ledger, "_run_trial", REAL_RUN_TRIAL) result = await client.post("/api/ledger/drafts/" + body["id"] + "/trial", json={"inputs": {}}) diff --git a/backend/tests/test_caliber_reimport.py b/backend/tests/test_caliber_reimport.py new file mode 100644 index 00000000..bb48ec95 --- /dev/null +++ b/backend/tests/test_caliber_reimport.py @@ -0,0 +1,848 @@ +"""K11 增量重导入与 B / L / R 三方合并:候选 R、当前图 L、字段基线 B 三者分开,候选不改 L,B 只在接受时推进。 + +这份文件盯住任务书 K11 的硬要求: + +1. **只认稳定 metric_id 和来源证据对齐**,名称相不相似不参与自动合并;同名不同范围必须人来定(test_same_name_...)。 +2. **逐字段三方状态**:无冲突更新、人工修改冲突、新增候选、缺失候选。漏提取不当删除(test_missing_...); + 人工改过的 L 不会因为「同一原文再提一次」被悄悄改回去(test_a_manual_override_...)。 +3. **候选不改 L,B 只在接受时推进**:建一次导入看得到工作项和冲突,但 L、B 一个字节不动;接受才落到图上并按被接受的 + 那几格推进 B,未接受的冲突不动 B。 +4. **baseline_unknown 必须人工对齐**:没有可比基线时逐字段判「需要人工对齐」,不假设 L = B,也不自动落。 +5. **未提供给模型的段落不能作引用**(test_invisible_citation_...)。 +6. **中断后可显式恢复**,不重复接受、不重复建版;request_id 幂等(重放不新增版本、同键不同内容报冲突)。 +7. 走真实 HTTP;模型一律注入假提取器、试跑换成假的,不连真实业务库。 +""" +from __future__ import annotations + +import copy +import uuid + +import pytest +from sqlalchemy import delete, select + +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, CaliberImportItem, CaliberImportRun, CaliberValidationRecord +from app.ledger import fieldbaseline, reimport +from tests.test_caliber_field_baseline import accepted_draft # noqa: F401 - 与基线用例共用起草帮手 +from tests.test_ledger_docdraft_api import ( # noqa: F401 - fixture 和起草用例共用 + client, datasource, documents, extract, fake_model, fake_trial, plan_reply, +) + + +@pytest.fixture(autouse=True) +def _fake_trial(fake_trial): + """假试跑本模块要一直挂着:走接口起草时它会去打夹具里不存在的库。""" + return fake_trial + + +@pytest.fixture(autouse=True) +def inline_import(monkeypatch): + """把后台导入换成同步执行:deterministic 地等它跑完再看结果(测试不发真实请求)。""" + async def run_now(run_id: str) -> None: + await reimport.run_import(run_id) + + monkeypatch.setattr(reimport, "start", run_now) + yield + + +@pytest.fixture(autouse=True) +async def _cleanup_imports(): + yield + async with SessionLocal() as session: + await session.execute(delete(CaliberImportItem)) + await session.execute(delete(CaliberImportRun)) + await session.execute(delete(CaliberValidationRecord)) + await session.commit() + + +def fake_extract(metrics: list[dict], visible: list[str], *, problems: list[dict] | None = None): + """假提取器:交回固定的候选 R 和可见段落(不调模型、不查库)。""" + async def run(**_kwargs): + return {"metrics": copy.deepcopy(metrics), "problems": list(problems or []), + "visible_chunk_ids": list(visible), "prompt_version": 1, "parse_version": 1, + "model_id": "fake-model", "sql_groups": []} + + return run + + +def candidate(doc: str, *, metric_id: str = "", name: str = "已支付退款率", unit: str = "%", decimals: int = 2, + text: str = "已支付订单里发生退款的比例", citations: list[dict] | None = None, + drop: tuple[str, ...] = ()) -> dict: + """一条候选 R:默认和 K05 基线一模一样(引用 doc-2)。drop 里的字段整格不交(模拟漏提取)。""" + definition = {"text": text, "scope": "全部门店", "exclusions": [], "owner": "运营", + "effective_from": "2026-01-01", + "citations": citations if citations is not None + else [{"chunk": f"{doc}-2", "quote": "只算已支付的订单", "document_id": doc, "span": [8, 16]}]} + metric = {"id": metric_id, "name": name, "synonyms": ["退款率"], "unit": unit, "decimals": decimals, + "expression": "cell(nodes.fetch, 0, 'refund_rate')", "definition": definition, + "open_questions": []} + for path in drop: + head, _, tail = path[1:].partition("/") + if tail: + metric.get(head, {}).pop(tail, None) + else: + metric.pop(head, None) + return metric + + +async def baseline_draft(client, documents, datasource, monkeypatch) -> tuple[dict, str]: + """走一次真实起草,返回 (草稿详情, 文档 id)。草稿详情里有字段基线 B 和基准版本 revision。""" + doc = await documents("k11-" + uuid.uuid4().hex[:8]) + source_id = await datasource() + fake_model(monkeypatch, plan_reply(f"{doc}-2")) + body = await extract(client, doc, source_id) + made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json() + return made, doc + + +async def make_import(client, draft_id: str, doc: str, metrics: list[dict], visible: list[str], + monkeypatch, *, request_id: str | None = None) -> dict: + monkeypatch.setattr(reimport, "extract_candidates", fake_extract(metrics, visible)) + body = {"request_id": request_id} if request_id else {} + created = await client.post(f"/api/ledger/drafts/{draft_id}/imports", json=body) + assert created.status_code == 201, created.text + run_id = created.json()["run_id"] + got = await client.get(f"/api/ledger/imports/{run_id}") + assert got.status_code == 200, got.text + return got.json() + + +def states(item: dict) -> dict[str, str]: + return {cell["path"]: cell["state"] for cell in item["fields"]} + + +# ========================================================================== +# 1. 无冲突更新 + B 只在接受时推进 +# ========================================================================== + +async def test_no_conflict_update_lands_on_accept_and_b_advances_only_then(client, documents, datasource, + monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + assert made["field_baseline"]["status"] == "known" + + run = await make_import(client, made["id"], doc, [ + candidate(doc, text="已支付订单里退款的比例(新说法)")], [f"{doc}-1", f"{doc}-2"], monkeypatch) + assert run["status"] == "succeeded" and len(run["items"]) == 1 + # R 的来源可还原:不可变快照 + 实际进提示的段落 + 解析/模型/提示版本 + assert run["source_snapshot"]["artifact_id"] and run["source_snapshot"]["content_hash"] + assert run["visible_chunk_ids"] == [f"{doc}-1", f"{doc}-2"] + assert run["prompt_version"] == 1 and run["parse_version"] == 1 and run["model_id"] == "fake-model" + item = run["items"][0] + assert item["metric_id"] == "m1" and item["align"]["mode"] == "evidence" + assert item["status"] == "update" + by_path = states(item) + assert by_path["/definition/text"] == "update" + assert by_path["/name"] == "unchanged" + + # 候选生成不改 L、不改 B:图上的内容还是起草时那一份,基线引用一个字没动 + before = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert before["metrics"][0]["definition"]["text"] == "已支付订单里发生退款的比例" + assert before["revision"] == made["revision"] + assert before["field_baseline"]["artifact_id"] == made["field_baseline"]["artifact_id"] + + accepted = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "auto": True}], "expected_revision": made["revision"], + "request_id": "k11-accept-1"}) + assert accepted.status_code == 200, accepted.text + body = accepted.json() + assert body["applied"] is True and body["replayed"] is False + assert body["revision"] == made["revision"] + 1 + + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["metrics"][0]["definition"]["text"] == "已支付订单里退款的比例(新说法)" + assert after["field_baseline"]["status"] == "known" + assert after["field_baseline"]["artifact_id"] != made["field_baseline"]["artifact_id"] + values = fieldbaseline.values({"artifact_id": after["field_baseline"]["artifact_id"]}, "m1") + assert values["/definition/text"] == "已支付订单里退款的比例(新说法)" # 接受的那一格推进了 B + assert values["/name"] == "已支付退款率" # 没提的格子原样 + assert after["field_baseline"]["accepted_revision"] == made["revision"] + 1 + # 历史按接受追加:上次那条基线还在 + assert [entry["artifact_id"] for entry in after["field_baseline_history"]][-1] \ + == after["field_baseline"]["artifact_id"] + + +# ========================================================================== +# 2. 人工修改冲突 / 人工覆盖不被同一原文重提悄悄改回去 +# ========================================================================== + +async def test_a_manual_edit_becomes_a_conflict_and_only_moves_when_accepted(client, documents, datasource, + monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + edited = await client.patch(f"/api/ledger/drafts/{made['id']}", json={ + "operations": [{"op": "set", "metric_id": "m1", "path": "/unit", "value": "单"}], + "expected_revision": made["revision"], "request_id": "k11-edit-1"}) + assert edited.status_code == 200 and edited.json()["change"]["applied"] is True + revision = edited.json()["revision"] + + run = await make_import(client, made["id"], doc, [candidate(doc, unit="百分比")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + item = run["items"][0] + assert states(item)["/unit"] == "conflict" + assert item["status"] == "conflict" + + # 没接受之前 B 不动(冲突的那一格还在老基线上) + mid = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert fieldbaseline.values({"artifact_id": mid["field_baseline"]["artifact_id"]}, "m1")["/unit"] == "%" + + accepted = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "fields": ["/unit"]}], "expected_revision": revision, + "request_id": "k11-edit-accept"}) + assert accepted.status_code == 200, accepted.text + + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["metrics"][0]["unit"] == "百分比" + assert fieldbaseline.values({"artifact_id": after["field_baseline"]["artifact_id"]}, "m1")["/unit"] == "百分比" + + +async def test_a_manual_override_is_not_silently_reverted_by_re_importing_the_same_text( + client, documents, datasource, monkeypatch): + """人工把 L 改成了「单」,重导入还是原文里的「%」(= B):这不算新说法,既不报冲突也不动 L。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + edited = await client.patch(f"/api/ledger/drafts/{made['id']}", json={ + "operations": [{"op": "set", "metric_id": "m1", "path": "/unit", "value": "单"}], + "expected_revision": made["revision"], "request_id": "k11-override-1"}) + assert edited.json()["change"]["applied"] is True + + run = await make_import(client, made["id"], doc, [candidate(doc, unit="%")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + assert states(run["items"][0])["/unit"] == "unchanged" + assert run["items"][0]["status"] == "unchanged" + + # auto 收不掉任何东西(没有可接受的格子),L 还是人工改的那一份 + refused = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "auto": True}], "expected_revision": edited.json()["revision"]}) + assert refused.status_code == 422 and refused.json()["code"] == reimport.IMPORT_NOTHING_SELECTED + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["metrics"][0]["unit"] == "单" + + +# ========================================================================== +# 3. 漏提取不当删除 +# ========================================================================== + +async def test_a_missing_field_is_never_a_deletion(client, documents, datasource, monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, + [candidate(doc, drop=("/definition/text",))], [f"{doc}-1", f"{doc}-2"], monkeypatch) + item = run["items"][0] + assert states(item)["/definition/text"] == "missing" + assert item["status"] == "partial" + + refused = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "fields": ["/definition/text"]}], "expected_revision": made["revision"]}) + assert refused.status_code == 422 and refused.json()["code"] == reimport.IMPORT_FIELD_NOT_ACCEPTABLE + assert "漏提取不当删除" in refused.json()["detail"] + + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["metrics"][0]["definition"]["text"] == "已支付订单里发生退款的比例" # L 原样 + assert after["field_baseline"]["artifact_id"] == made["field_baseline"]["artifact_id"] + + +async def test_a_brand_new_field_is_a_candidate_that_can_be_accepted(client, documents, datasource, monkeypatch): + """新增候选:R 提出了 B、L 都没有的字段(粒度),不是冲突,接受后落到 L 并推进 B。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + extra = candidate(doc) + extra["grain"] = "日" + run = await make_import(client, made["id"], doc, [extra], [f"{doc}-1", f"{doc}-2"], monkeypatch) + item = run["items"][0] + assert states(item)["/grain"] == "new" and item["status"] == "new" + + accepted = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "auto": True}], "expected_revision": made["revision"], + "request_id": "k11-new-field"}) + assert accepted.status_code == 200, accepted.text + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["metrics"][0]["grain"] == "日" + assert fieldbaseline.values({"artifact_id": after["field_baseline"]["artifact_id"]}, "m1")["/grain"] == "日" + + +# ========================================================================== +# 4. 同名不同范围:不按名字自动合并 +# ========================================================================== + +async def test_the_same_name_with_different_evidence_is_not_auto_merged(client, documents, datasource, monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + other = candidate(doc, name="已支付退款率", text="另一段范围里的退款率", + citations=[{"chunk": f"{doc}-1", "quote": "退款率 = 已支付后退款的订单数 / 已支付订单数", + "document_id": doc, "span": [0, 23]}]) + run = await make_import(client, made["id"], doc, [other], [f"{doc}-1", f"{doc}-2"], monkeypatch) + item = run["items"][0] + # 名字和图上那条一模一样,但引的原文不是同一段:不自动合并,交给人 + assert item["align"]["mode"] == "new" and item["metric_id"] == "" + assert item["status"] == "new" and item["name"] == "已支付退款率" + + # 没对齐的不能直接接受 + refused = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "已支付退款率", "auto": True}], "expected_revision": made["revision"]}) + assert refused.status_code == 409 and refused.json()["code"] == reimport.IMPORT_ITEM_UNKNOWN + + # 人来定:把它对到 m1 上,再按字段接受 + aligned = await client.post(f"/api/ledger/imports/{run['run_id']}/items/{item['item_id']}/align", + json={"metric_id": "m1"}) + assert aligned.status_code == 200, aligned.text + after_align = aligned.json()["items"][0] + assert after_align["metric_id"] == "m1" and after_align["align"]["manual"] is True + assert states(after_align)["/definition/text"] == "update" + + +# ========================================================================== +# 5. 引用不可见:没给过模型的段落不能当引用 +# ========================================================================== + +async def test_citations_to_segments_the_model_never_saw_are_dropped(client, documents, datasource, monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + hidden = {"chunk": "hidden-9", "quote": "模型没看到过的原文"} + kept = {"chunk": f"{doc}-2", "quote": "退款率按门店拆", "document_id": doc, "span": [0, 7]} + run = await make_import(client, made["id"], doc, + [candidate(doc, citations=[kept, hidden])], [f"{doc}-1", f"{doc}-2"], monkeypatch) + item = run["items"][0] + assert [entry["chunk"] for entry in item["align"]["invisible_citations"]] == ["hidden-9"] + citations_field = next(cell for cell in item["fields"] if cell["path"] == "/definition/citations") + assert [entry["chunk"] for entry in citations_field["r"]] == [f"{doc}-2"] + + accepted = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "fields": ["/definition/citations"]}], + "expected_revision": made["revision"], "request_id": "k11-cite-1"}) + assert accepted.status_code == 200, accepted.text + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + chunks = [entry.get("chunk") for entry in after["metrics"][0]["definition"]["citations"]] + assert chunks == [f"{doc}-2"] and "hidden-9" not in chunks + + +async def test_a_candidate_whose_only_citation_is_invisible_fails(client, documents, datasource, monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, + [candidate(doc, citations=[{"chunk": "hidden-9", "quote": "没给模型的原文"}])], + [f"{doc}-1"], monkeypatch) + item = run["items"][0] + assert item["status"] == "failed" and item["failed"] is True + assert "没有提供给模型" in item["error"] + + +async def test_a_failed_item_is_never_acceptable_and_never_clears_citations(client, documents, datasource, + monkeypatch): + """整条失败的候选(引用一段都没核对上):任何一格都不能接受,更不能用空的 R 把 citations 清掉。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, + [candidate(doc, citations=[{"chunk": "hidden-9", "quote": "没给模型的原文"}])], + [f"{doc}-1"], monkeypatch) + item = run["items"][0] + assert item["status"] == "failed" and item["failed"] is True + # UI 读得到的普通字段:整条失败的一格都不可接受 + assert all(cell["acceptable"] is False for cell in item["fields"]) + + revision = made["revision"] + for selection, code in ( + ({"item_id": item["item_id"], "fields": ["/definition/citations"]}, reimport.IMPORT_ITEM_FAILED), + ({"item_id": item["item_id"], "fields": ["/unit"]}, reimport.IMPORT_ITEM_FAILED), + ({"item_id": item["item_id"], "auto": True}, reimport.IMPORT_NOTHING_SELECTED)): + refused = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", + json={"items": [selection], "expected_revision": revision}) + assert refused.status_code == 422 and refused.json()["code"] == code, refused.text + + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["metrics"][0]["definition"]["citations"] # L 的出处没被清掉 + assert after["revision"] == revision + assert after["field_baseline"]["artifact_id"] == made["field_baseline"]["artifact_id"] + + +# ========================================================================== +# 4b. 工作项定位:按 item_id,不按 metric_id / 位置;跨组重号不当稳定身份 +# ========================================================================== + +async def test_accept_and_reject_locate_by_item_id_and_never_take_the_last_duplicate(client, documents, + datasource, monkeypatch): + """两条候选都对到 m1:按 metric_id 定位会歧义(回 409,不取最后一条),按 item_id 才落得下去。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, + [candidate(doc, text="第一种说法"), candidate(doc, text="第二种说法")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + items = run["items"] + assert len(items) == 2 and {item["metric_id"] for item in items} == {"m1"} + + ambiguous = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "fields": ["/definition/text"]}], "expected_revision": made["revision"]}) + assert ambiguous.status_code == 409 and ambiguous.json()["code"] == reimport.IMPORT_ITEM_AMBIGUOUS + assert sorted(ambiguous.json()["item_ids"]) == sorted(item["item_id"] for item in items) + assert (await client.get(f"/api/ledger/drafts/{made['id']}")).json()["revision"] == made["revision"] + + rejected = await client.post(f"/api/ledger/imports/{run['run_id']}/reject", json={ + "items": [{"metric_id": "m1"}]}) + assert rejected.status_code == 409 and rejected.json()["code"] == reimport.IMPORT_ITEM_AMBIGUOUS + + # 按 item_id 定位:只动那一条 + first = items[0] + done = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"item_id": first["item_id"], "fields": ["/definition/text"]}], + "expected_revision": made["revision"], "request_id": "k11-item-id-1"}) + assert done.status_code == 200, done.text + after = (await client.get(f"/api/ledger/imports/{run['run_id']}")).json()["items"] + decided = next(item for item in after if item["item_id"] == first["item_id"]) + other = next(item for item in after if item["item_id"] != first["item_id"]) + assert "/definition/text" in decided["accepted"] and other["accepted"] == [] + + +async def test_a_cross_group_duplicate_candidate_id_is_not_a_stable_identity(client, documents, datasource, + monkeypatch): + """模型在两组里各自从 m1 编起(跨组重号):这个编号不当稳定身份,只按来源证据对。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + first = candidate(doc, metric_id="m1", text="说法 A") # 引 doc-2,和图上那条同源 + second = candidate(doc, metric_id="m1", name="另一条指标", text="说法 B", # 同一个编号,但引 doc-1 + citations=[{"chunk": f"{doc}-1", "quote": "退款率 = 已支付后退款的订单数 / 已支付订单数", + "document_id": doc, "span": [0, 23]}]) + run = await make_import(client, made["id"], doc, [first, second], [f"{doc}-1", f"{doc}-2"], monkeypatch) + by_name = {item["name"]: item for item in run["items"]} + aligned = by_name["已支付退款率"] + assert aligned["metric_id"] == "m1" and aligned["align"]["mode"] == "evidence" + assert "重号" in aligned["align"]["identity_note"] and aligned["align"]["identity_note"] + # 另一条虽然也叫 m1,但证据不同:没有被当成「m1」对上 + other = by_name["另一条指标"] + assert other["metric_id"] == "" and other["align"]["mode"] == "new" + + +# ========================================================================== +# 6. baseline_unknown:必须人工对齐,不能假设 L = B +# ========================================================================== + +async def _clear_baseline(draft_id: str) -> None: + async with SessionLocal() as session: + draft = await session.get(CaliberDraft, draft_id) + payload = dict(draft.payload) + payload.pop(fieldbaseline.REF_KEY, None) + payload.pop(fieldbaseline.HISTORY_KEY, None) + draft.payload = payload + await session.commit() + + +async def test_baseline_unknown_needs_manual_alignment_and_builds_b_from_accepted_fields( + client, documents, datasource, monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + await _clear_baseline(made["id"]) + assert (await client.get(f"/api/ledger/drafts/{made['id']}")).json()["field_baseline"]["status"] \ + == "baseline_unknown" + + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的一版说明")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + item = run["items"][0] + assert item["status"] == "manual" and states(item)["/definition/text"] == "manual" + + # 没有可比基线:auto 一格都不收(不假设 L = B) + refused = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "auto": True}], "expected_revision": made["revision"]}) + assert refused.status_code == 422 and refused.json()["code"] == reimport.IMPORT_NOTHING_SELECTED + + # 人明确点名接受这一格:B 从这一格建起来(只有接受的那几格有基线) + accepted = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "fields": ["/definition/text"]}], "expected_revision": made["revision"], + "request_id": "k11-unknown-1"}) + assert accepted.status_code == 200, accepted.text + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["field_baseline"]["status"] == "known" + values = fieldbaseline.values({"artifact_id": after["field_baseline"]["artifact_id"]}, "m1") + assert values["/definition/text"] == "新的一版说明" + assert "/name" not in values # 只接受了这一格,别的不倒填历史 + + +# ========================================================================== +# 7. 中断恢复 + 幂等 +# ========================================================================== + +async def test_recovery_preserves_decisions_and_does_not_create_another_version(client, documents, datasource, + monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + aligned = candidate(doc, text="新的说明") + unaligned = candidate(doc, name="另一条指标", citations=[ + {"chunk": f"{doc}-1", "quote": "退款率 = 已支付后退款的订单数 / 已支付订单数", + "document_id": doc, "span": [0, 23]}]) + run = await make_import(client, made["id"], doc, [aligned, unaligned], [f"{doc}-1", f"{doc}-2"], monkeypatch) + assert [item["status"] for item in run["items"]] == ["update", "new"] + + accepted = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "fields": ["/definition/text"]}], + "expected_revision": made["revision"], "request_id": "k11-resume-1"}) + assert accepted.status_code == 200, accepted.text + revision = accepted.json()["revision"] + + # 模拟服务中断:状态记 interrupted,工作项留着 + async with SessionLocal() as session: + row = await session.get(CaliberImportRun, run["run_id"]) + row.status, row.finished_at = "interrupted", None + await session.commit() + + resumed = await client.post(f"/api/ledger/imports/{run['run_id']}/resume", json={}) + assert resumed.status_code == 200, resumed.text + body = (await client.get(f"/api/ledger/imports/{run['run_id']}")).json() + assert body["status"] in ("succeeded", "partial") + # 已经接受的那一格还是接受的,没有多建版本 + decided = next(item for item in body["items"] if item["metric_id"] == "m1") + assert decided["status"] == "accepted" and "/definition/text" in decided["accepted"] + draft_now = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert draft_now["revision"] == revision + + +async def test_startup_reaper_marks_a_running_import_interrupted_and_resume_continues(client, documents, datasource, + monkeypatch): + """进程被杀之后:启动整理把排队/进行中的导入记成 interrupted,工作项留着;人点恢复接着做,不串项。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的说明")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + run_id = run["run_id"] + # 模拟「进程被强杀,库里还记着进行中」:属主是已经不在的进程,工作项还没决定 + async with SessionLocal() as session: + row = await session.get(CaliberImportRun, run_id) + row.status, row.owner, row.finished_at = "running", "a-dead-worker", None + item = (await session.execute(select(CaliberImportItem).where( + CaliberImportItem.run_id == run_id))).scalars().one() + item.status = "pending" + await session.commit() + + await reimport.startup() + got = (await client.get(f"/api/ledger/imports/{run_id}")).json() + assert got["status"] == "interrupted" + assert got["items"][0]["status"] == "pending" # 工作项原样留着,可恢复 + + monkeypatch.setattr(reimport, "extract_candidates", + fake_extract([candidate(doc, text="新的说明")], [f"{doc}-1", f"{doc}-2"])) + resumed = await client.post(f"/api/ledger/imports/{run_id}/resume", json={}) + assert resumed.status_code == 200, resumed.text + final = (await client.get(f"/api/ledger/imports/{run_id}")).json() + assert final["status"] == "succeeded" and len(final["items"]) == 1 + assert final["items"][0]["status"] == "update" and final["items"][0]["metric_id"] == "m1" + + +async def test_resume_matches_items_by_alignment_key_and_never_moves_decisions(client, documents, datasource, + monkeypatch): + """恢复不能按候选位置搬决定:顺序倒过来、条数变少,工作项还是原来那几条,决定仍挂在各自身上。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + first = candidate(doc, text="说法 A") # 引 doc-2 → 对到 m1 + second = candidate(doc, name="另一条指标", citations=[ + {"chunk": f"{doc}-1", "quote": "退款率 = 已支付后退款的订单数 / 已支付订单数", + "document_id": doc, "span": [0, 23]}]) # 引 doc-1 → 没对上 + run = await make_import(client, made["id"], doc, [first, second], [f"{doc}-1", f"{doc}-2"], monkeypatch) + items = {item["name"]: item for item in run["items"]} + aligned, other = items["已支付退款率"], items["另一条指标"] + + rejected = await client.post(f"/api/ledger/imports/{run['run_id']}/reject", + json={"items": [{"item_id": other["item_id"]}]}) + assert rejected.status_code == 200, rejected.text + + # 中断之后重抽:这次候选**倒着来**(顺序、条数都和上一次不同) + async with SessionLocal() as session: + row = await session.get(CaliberImportRun, run["run_id"]) + row.status = "interrupted" + await session.commit() + monkeypatch.setattr(reimport, "extract_candidates", fake_extract([second, first], [f"{doc}-1", f"{doc}-2"])) + assert (await client.post(f"/api/ledger/imports/{run['run_id']}/resume", json={})).status_code == 200 + + after = (await client.get(f"/api/ledger/imports/{run['run_id']}")).json() + by_id = {item["item_id"]: item for item in after["items"]} + assert set(by_id) == {aligned["item_id"], other["item_id"]} # 没有多出新项,也没有替换掉 + assert by_id[other["item_id"]]["status"] == "rejected" # 拒绝仍挂在它自己身上 + assert by_id[other["item_id"]]["metric_id"] == "" + assert by_id[aligned["item_id"]]["rejected"] == [] and by_id[aligned["item_id"]]["metric_id"] == "m1" + # 每项自己的来源依据没被新一轮覆盖 + assert by_id[other["item_id"]]["align"]["evidence"] == [f"{doc}-1"] + assert by_id[aligned["item_id"]]["align"]["evidence"] == [f"{doc}-2"] + + # 条数再变少:这次只抽到对到 m1 的那一条,别的项原样留着(决定不丢) + async with SessionLocal() as session: + row = await session.get(CaliberImportRun, run["run_id"]) + row.status = "interrupted" + await session.commit() + monkeypatch.setattr(reimport, "extract_candidates", fake_extract([first], [f"{doc}-1", f"{doc}-2"])) + assert (await client.post(f"/api/ledger/imports/{run['run_id']}/resume", json={})).status_code == 200 + shrunk = (await client.get(f"/api/ledger/imports/{run['run_id']}")).json()["items"] + kept = {item["item_id"]: item for item in shrunk} + assert other["item_id"] in kept and kept[other["item_id"]]["status"] == "rejected" + + +async def test_auto_only_takes_undecided_cells_and_skips_decided_ones(client, documents, datasource, monkeypatch): + """auto 只收还没决定的「无冲突更新 / 新增候选」:已经拒绝过的那一格不再被 auto 碰。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的说明", unit="百分比")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + item = run["items"][0] + assert states(item)["/unit"] == "update" and states(item)["/definition/text"] == "update" + + rejected = await client.post(f"/api/ledger/imports/{run['run_id']}/reject", json={ + "items": [{"item_id": item["item_id"], "fields": ["/unit"]}]}) + assert rejected.status_code == 200, rejected.text + + accepted = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"item_id": item["item_id"], "auto": True}], "expected_revision": made["revision"], + "request_id": "k11-auto-1"}) + assert accepted.status_code == 200, accepted.text + after_item = (await client.get(f"/api/ledger/imports/{run['run_id']}")).json()["items"][0] + assert after_item["accepted"] == ["/definition/text"] and after_item["rejected"] == ["/unit"] + + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["metrics"][0]["definition"]["text"] == "新的说明" # auto 收了 + assert after["metrics"][0]["unit"] == "%" # 拒绝的那一格没被 auto 收掉 + + +async def test_a_live_change_after_the_candidate_refuses_accept_until_refreshed(client, documents, datasource, + monkeypatch): + """候选算出来之后 L 被人改过:只把 expected_revision 更新到最新一版也不许覆盖,要先刷新三方再确认。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的说明")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + item = run["items"][0] + + edited = await client.patch(f"/api/ledger/drafts/{made['id']}", json={ + "operations": [{"op": "set", "metric_id": "m1", "path": "/unit", "value": "单"}], + "expected_revision": made["revision"], "request_id": "k11-touch-1"}) + assert edited.status_code == 200 and edited.json()["change"]["applied"] is True + latest = edited.json()["revision"] + + stale = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"item_id": item["item_id"], "fields": ["/definition/text"]}], "expected_revision": latest}) + assert stale.status_code == 409 and stale.json()["code"] == reimport.IMPORT_STALE_L, stale.text + assert "刷新" in stale.json()["detail"] + fresh = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert fresh["metrics"][0]["definition"]["text"] == "已支付订单里发生退款的比例" # 一点没落 + assert fresh["revision"] == latest + + # 刷新三方(按现在的 L 重算)之后,人重新确认再接受 + refreshed = await client.post(f"/api/ledger/imports/{run['run_id']}/refresh", json={}) + assert refreshed.status_code == 200, refreshed.text + assert states(refreshed.json()["items"][0])["/unit"] == "unchanged" # 三方跟着新的 L 走了 + ok = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"item_id": item["item_id"], "fields": ["/definition/text"]}], "expected_revision": latest, + "request_id": "k11-stale-1"}) + assert ok.status_code == 200 and ok.json()["applied"] is True, ok.text + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["metrics"][0]["definition"]["text"] == "新的说明" + assert after["metrics"][0]["unit"] == "单" # 人工改的那一格没被覆盖 + + +async def test_resume_refuses_while_queued_or_running_with_the_matching_wording(client, documents, datasource, + monkeypatch): + """恢复正在排队 / 正在运行的那一次导入:回 409,文案按状态说「排队中 / 正在运行」。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的说明")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + for status, word in (("queued", "排队中"), ("running", "正在运行")): + async with SessionLocal() as session: + row = await session.get(CaliberImportRun, run["run_id"]) + row.status = status + await session.commit() + refused = await client.post(f"/api/ledger/imports/{run['run_id']}/resume", json={}) + assert refused.status_code == 409 and refused.json()["code"] == reimport.IMPORT_ALREADY_RUNNING + assert word in refused.json()["detail"] and refused.json()["status"] == status + + +async def test_accept_is_idempotent_by_request_id(client, documents, datasource, monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的说明")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + body = {"items": [{"metric_id": "m1", "fields": ["/definition/text"]}], + "expected_revision": made["revision"], "request_id": "k11-idem-1"} + first = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json=body) + assert first.status_code == 200 and first.json()["applied"] is True + revision = first.json()["revision"] + + replay = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json=body) + assert replay.status_code == 200 and replay.json()["replayed"] is True + assert replay.json()["revision"] == revision + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["revision"] == revision + # 重放交回的是**已提交的结果**:B 读得回来,而且就是第一次那次接受推进出来的那一件 + assert after["field_baseline"]["status"] == "known" and after["field_baseline"]["readable"] is True + assert fieldbaseline.values({"artifact_id": after["field_baseline"]["artifact_id"]}, "m1")["/definition/text"] \ + == "新的说明" + + clash = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + **body, "items": [{"metric_id": "m1", "fields": ["/unit"]}]}) + assert clash.status_code == 409 and clash.json()["code"] == reimport.IMPORT_IDEMPOTENCY_CONFLICT + + +# ========================================================================== +# 8. 原子性:先写 B 工件,再一个事务提交 L + 工作项决定 + 新 B 引用 +# ========================================================================== + +async def _request_rows(request_id: str) -> list[Any]: + from app.db.models import CaliberWriteRequest + + async with SessionLocal() as session: + return list((await session.execute(select(CaliberWriteRequest).where( + CaliberWriteRequest.request_id == request_id))).scalars()) + + +async def _version_count(workflow_id: str) -> int: + from app.db.models import WorkflowVersion + + async with SessionLocal() as session: + return len(list((await session.execute(select(WorkflowVersion).where( + WorkflowVersion.workflow_id == workflow_id))).scalars())) + + +async def _draft_revision(draft_id: str) -> int: + async with SessionLocal() as session: + draft = await session.get(CaliberDraft, draft_id) + return draft.payload.get("version") if isinstance(draft.payload, dict) else None + + +async def test_a_baseline_write_failure_keeps_l_uncommitted_and_the_retry_succeeds( + client, documents, datasource, monkeypatch): + """故障注入:B 工件写不进去 → L 不提交(没有新版本、没有幂等记录),修好之后同一个 request_id 重试成功。""" + from app.core import artifact_store + + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的说明")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + before_versions = await _version_count(made["workflow_id"]) + request_id = "k11-atomic-baseline" + body = {"items": [{"metric_id": "m1", "fields": ["/definition/text"]}], + "expected_revision": made["revision"], "request_id": request_id} + + real_put_json = artifact_store.put_json + + async def boom(*_args, **_kwargs): + raise OSError("工件库写不进去") + + monkeypatch.setattr(artifact_store, "put_json", boom) + failed = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json=body) + assert failed.status_code == 503 and failed.json()["code"] == reimport.IMPORT_BASELINE_UNAVAILABLE, failed.text + + # 新 L 一个字节都没可见:版本、图内容、B 引用都没动;幂等记录也没落下(重试仍是「第一次」) + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["revision"] == made["revision"] and await _version_count(made["workflow_id"]) == before_versions + assert after["metrics"][0]["definition"]["text"] == "已支付订单里发生退款的比例" + assert after["field_baseline"]["artifact_id"] == made["field_baseline"]["artifact_id"] + assert await _request_rows(request_id) == [] + + # 修好工件库:同一个 request_id 重试(不是回放,是第一次真正落库),只多一版,B 跟着推进 + monkeypatch.setattr(artifact_store, "put_json", real_put_json) + retried = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json=body) + assert retried.status_code == 200 and retried.json()["applied"] is True, retried.text + assert await _version_count(made["workflow_id"]) == before_versions + 1 + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["metrics"][0]["definition"]["text"] == "新的说明" + assert fieldbaseline.values({"artifact_id": after["field_baseline"]["artifact_id"]}, "m1")["/definition/text"] \ + == "新的说明" + + +async def test_a_failure_after_the_baseline_write_rolls_l_back(client, documents, datasource, monkeypatch): + """回滚:B 工件已经写了(孤儿,可以接受),但提交那一步失败 → L 不提交、幂等记录不落,重试仍能成功。""" + from app.apps import versions as versions_mod + from app.apps.versions import WorkflowChanged + + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的说明")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + before_versions = await _version_count(made["workflow_id"]) + request_id = "k11-atomic-rollback" + body = {"items": [{"metric_id": "m1", "fields": ["/definition/text"]}], + "expected_revision": made["revision"], "request_id": request_id} + + real_save_graph = versions_mod.save_graph + + async def boom(*_args, **_kwargs): + raise WorkflowChanged("人工制造的并发写入失败") + + monkeypatch.setattr(versions_mod, "save_graph", boom) + failed = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json=body) + assert failed.status_code == 409 and failed.json()["code"] == reimport.IMPORT_STALE_REVISION, failed.text + + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["revision"] == made["revision"] and await _version_count(made["workflow_id"]) == before_versions + assert after["metrics"][0]["definition"]["text"] == "已支付订单里发生退款的比例" + assert after["field_baseline"]["artifact_id"] == made["field_baseline"]["artifact_id"] + assert await _request_rows(request_id) == [] + + monkeypatch.setattr(versions_mod, "save_graph", real_save_graph) + retried = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json=body) + assert retried.status_code == 200 and retried.json()["applied"] is True, retried.text + assert await _version_count(made["workflow_id"]) == before_versions + 1 + + +async def test_partial_baseline_coverage_is_reported_and_other_fields_stay_manual( + client, documents, datasource, monkeypatch): + """baseline_unknown 上人工逐字段接受:B 只覆盖被接受的那几格,coverage 是 partial(不能报成整卡 known)。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + await _clear_baseline(made["id"]) + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的一版说明", unit="百分比")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + accepted = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "fields": ["/definition/text"]}], "expected_revision": made["revision"], + "request_id": "k11-partial-1"}) + assert accepted.status_code == 200, accepted.text + + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + baseline = after["field_baseline"] + assert baseline["status"] == "known" and baseline["readable"] is True + coverage = baseline["coverage"] + assert coverage["status"] == "partial" + assert "/name" in coverage["metrics"]["m1"]["missing"] # 没接受的格照实说没有基线 + assert coverage["metrics"]["m1"]["covered"] == 1 + assert coverage["metrics"]["m1"]["expected"] > 1 + + # 还有别的说法、又没有可比基线的格子仍旧是「需要人工对齐」,不会被悄悄升格成「无冲突更新」或「冲突」 + item = (await client.get(f"/api/ledger/imports/{run['run_id']}")).json()["items"][0] + by_path = states(item) + assert by_path["/unit"] == "manual" + assert "/definition/text" in item["accepted"] + + # auto 收不掉没有基线的格子:还要人逐条点名 + refused = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "auto": True}], "expected_revision": after["revision"]}) + assert refused.status_code == 422 and refused.json()["code"] == reimport.IMPORT_NOTHING_SELECTED + assert (await client.get(f"/api/ledger/drafts/{made['id']}")).json()["metrics"][0]["unit"] == "%" + + +async def test_the_first_accept_keeps_a_complete_coverage(client, documents, datasource, monkeypatch): + """首次接受导入收的是整张卡:coverage 是 complete(和按字段推进出来的 partial 分开说)。""" + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + assert made["field_baseline"]["coverage"]["status"] == "complete" + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的说明")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + accepted = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "fields": ["/definition/text"]}], "expected_revision": made["revision"], + "request_id": "k11-complete-1"}) + assert accepted.status_code == 200, accepted.text + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["field_baseline"]["coverage"]["status"] == "complete" + assert after["field_baseline"]["coverage"]["metrics"]["m1"]["missing"] == [] + + +async def test_create_run_is_idempotent_by_request_id(client, documents, datasource, monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + monkeypatch.setattr(reimport, "extract_candidates", fake_extract([candidate(doc)], [f"{doc}-2"])) + first = await client.post(f"/api/ledger/drafts/{made['id']}/imports", json={"request_id": "k11-run-1"}) + again = await client.post(f"/api/ledger/drafts/{made['id']}/imports", json={"request_id": "k11-run-1"}) + assert first.json()["run_id"] == again.json()["run_id"] + listed = await client.get(f"/api/ledger/drafts/{made['id']}/imports") + assert listed.status_code == 200 and len(listed.json()["runs"]) == 1 + async with SessionLocal() as session: + rows = list((await session.execute(select(CaliberImportRun).where( + CaliberImportRun.draft_id == made["id"]))).scalars()) + assert len(rows) == 1 + + +async def test_stale_revision_is_refused(client, documents, datasource, monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的说明")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + stale = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "fields": ["/definition/text"]}], "expected_revision": 99}) + assert stale.status_code == 409 and stale.json()["code"] == reimport.IMPORT_STALE_REVISION + assert stale.json()["current_version"] == made["revision"] + + missing = await client.post(f"/api/ledger/imports/{run['run_id']}/accept", json={ + "items": [{"metric_id": "m1", "fields": ["/definition/text"]}]}) + assert missing.status_code == 409 and missing.json()["code"] == reimport.IMPORT_REVISION_REQUIRED + + +async def test_reject_keeps_l_and_b_untouched(client, documents, datasource, monkeypatch): + made, doc = await baseline_draft(client, documents, datasource, monkeypatch) + run = await make_import(client, made["id"], doc, [candidate(doc, text="新的说明")], + [f"{doc}-1", f"{doc}-2"], monkeypatch) + rejected = await client.post(f"/api/ledger/imports/{run['run_id']}/reject", json={ + "items": [{"metric_id": "m1", "fields": ["/definition/text"]}], "note": "先不改"}) + assert rejected.status_code == 200, rejected.text + body = rejected.json() + assert body["items"][0]["status"] == "rejected" and "/definition/text" in body["items"][0]["rejected"] + after = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert after["metrics"][0]["definition"]["text"] == "已支付订单里发生退款的比例" + assert after["field_baseline"]["artifact_id"] == made["field_baseline"]["artifact_id"] + assert after["revision"] == made["revision"] diff --git a/backend/tests/test_caliber_selection.py b/backend/tests/test_caliber_selection.py new file mode 100644 index 00000000..5e11cfc5 --- /dev/null +++ b/backend/tests/test_caliber_selection.py @@ -0,0 +1,329 @@ +"""K08 S5/S6:口径卡的指标选择(caliber_from.metrics)在运行时、画布校验、对账与召回里的一致解释。 + +拍板要点(任务书 K08): + +- caliber_from.metrics 是**可选选择**,缺省整卡;给了就只算选中的那些(按源卡顺序归一)——未知、空的**响亮失败**, + 绝不退回整卡(退回去算的是别的指标); +- 绑定判定只看**过滤后的真实定义**:B 独有(或和 A 共享一条 SQL 上的说法)的问题不牵连 A; +- ``nodes.<卡>.metrics[i]`` 的 i 落在**这次真正算出来的那份数组**(有效数组)上,不是全量定义那份:运行时算出的指标集、 + 对账卡、召回卡建位置引用时都按同一份(ledger.closure.selection_index); +- 老图(没写选择)行为一字不变。 + +引擎用例用 tests/binding_samples 的合成订单夹具(旧定义 3 单 900 元 / 新定义 2 单 500 元),真跑探索运行,不发模型请求。 +""" +from __future__ import annotations + +import pytest +from sqlalchemy import delete, select as sa_select + +from app.core import artifact_store +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, DataSource, RunEvent, Workflow, WorkflowVersion +from app.engine.runner import run_manager +from app.engine.schema import GraphSpec, validate_graph +from tests import binding_samples as S +from tests.ledger_samples import wait as wait_run + +#: 这个文件自己建的工作流(连同版本、草稿)和临时数据源跑完删掉 +OWN_PREFIX = "K08 " + + +# ========================================================================== +# 夹具 +# ========================================================================== + + +@pytest.fixture(autouse=True) +async def cleanup_own_rows(): + yield + async with SessionLocal() as session: + ids = list((await session.execute( + sa_select(Workflow.id).where(Workflow.name.like(f"{OWN_PREFIX}%")))).scalars()) + if ids: + for model in (WorkflowVersion, CaliberDraft): + await session.execute(delete(model).where(model.workflow_id.in_(ids))) + await session.execute(delete(Workflow).where(Workflow.id.in_(ids))) + for name in S.MADE["sources"]: + await session.execute(delete(DataSource).where(DataSource.name == name)) + S.MADE["sources"].clear() + await session.commit() + + +@pytest.fixture(autouse=True) +async def order_db(tmp_path): + await S.fresh_source(tmp_path / "orders.db") + yield + + +@pytest.fixture(autouse=True) +async def engine_up(): + await run_manager.setup() + yield + await run_manager.shutdown() + + +async def run(graph: dict) -> object: + started = await run_manager.start(graph=graph, input_payload=dict(S.OCTOBER)) + return await wait_run(started.id) + + +async def card_of(run_id: str, node_id: str = "card") -> dict: + async with SessionLocal() as session: + event = (await session.execute(sa_select(RunEvent).where( + RunEvent.run_id == run_id, RunEvent.type == "node.finished", + RunEvent.node_id == node_id))).scalars().one() + return artifact_store.load(event.data["artifact"]) + + +def card_config(graph: dict, node_id: str = "card") -> dict: + return next(n for n in graph["nodes"] if n["id"] == node_id)["data"]["config"] + + +def with_selection(graph: dict, metrics, *, node_id: str = "card") -> dict: + card_config(graph, node_id).setdefault("caliber_from", {})["metrics"] = metrics + return graph + + +async def upstream_v1(name: str = "K08 上游") -> dict: + return await S.upstream(name=f"{OWN_PREFIX}{name}") + + +# ========================================================================== +# 选择的核心:唯一一份解释(和闭包同一处) +# ========================================================================== + + +def test_effective_metrics_and_index_share_one_interpretation(): + from app.engine.nodes import metrics + from app.ledger import closure + + defs = [{"id": "a"}, {"id": "b"}, {"id": "c"}] + assert [m["id"] for m in metrics.effective_metrics(defs, ["c", "a"])] == ["a", "c"] + assert metrics.selection_index(defs, ["c", "a"]) == [0, 2] + # 有效数组和下标是同一份解释的两种写法 + assert [defs[i]["id"] for i in metrics.selection_index(defs, ["c", "a"])] == \ + [m["id"] for m in metrics.effective_metrics(defs, ["c", "a"])] + # 位置与取舍只由 closure.selection_index 算,运行时不再各写一遍 + assert metrics.selection_index(defs, ["c", "a"]) == list(closure.selection_index(defs, ["c", "a"]).positions) + # 缺省整卡:顺序与条目一个不动 + assert metrics.effective_metrics(defs, None) == defs + assert metrics.selection_index(defs, None) == [0, 1, 2] + + +def test_require_selection_is_loud_and_never_falls_back_to_the_whole_card(): + from app.engine.nodes.metrics import SelectionRefused, require_selection + + defs = [{"id": "a"}, {"id": "b"}] + with pytest.raises(SelectionRefused, match="没有指标"): + require_selection(defs, ["没有这个"]) + with pytest.raises(SelectionRefused, match="一个指标也没选"): + require_selection(defs, []) + for bad in ("a", [1], ["a", ""]): + with pytest.raises(SelectionRefused): + require_selection(defs, bad) + + +# ========================================================================== +# 运行时:只算选中的那几个,未知 / 空的选择响亮失败 +# ========================================================================== + + +async def test_runtime_computes_only_the_selected_metrics(): + up = await upstream_v1() + row = await run(with_selection(S.chained_graph(up, version=1), ["m2"])) + assert row.status == "succeeded", row.error + card = await card_of(row.id) + assert [m["id"] for m in card["metrics"]] == ["m2"] and card["metrics"][0]["value"] == 900.0 + # 来源照记选择(按源卡顺序),证据据此认得这次算的是哪几个 + assert card["source"]["metrics"] == ["m2"] + + +async def test_an_unknown_selection_fails_the_node_loudly(): + up = await upstream_v1() + row = await run(with_selection(S.chained_graph(up, version=1), ["没有这个"])) + assert row.status == "failed" + assert "没有指标" in str(row.error) and "没有这个" in str(row.error) + assert "m1" in str(row.error) and "m2" in str(row.error) # 说清卡上有哪些 + + +async def test_an_empty_selection_is_refused_and_never_treated_as_the_whole_card(): + """显式空选择:画布校验就拦住(运行时那条兜底见 require_selection 的用例),都不当作整卡。""" + up = await upstream_v1() + with pytest.raises(ValueError, match="是空的"): + await run(with_selection(S.chained_graph(up, version=1), [])) + + +async def test_an_old_graph_without_a_selection_is_unchanged(): + """没写选择:整卡照算,来源里没有这项。""" + up = await upstream_v1() + row = await run(S.chained_graph(up, version=1)) + assert row.status == "succeeded", row.error + card = await card_of(row.id) + assert [m["id"] for m in card["metrics"]] == ["m1", "m2"] + assert "metrics" not in card["source"] + + +async def test_a_shared_query_is_kept_for_the_selected_metric(): + """m1 / m2 共享同一条 SQL:只选 m1 时那条 SQL 照旧执行(不然 m1 取不到数)。""" + up = await upstream_v1() + row = await run(with_selection(S.chained_graph(up, version=1), ["m1"])) + assert row.status == "succeeded", row.error + card = await card_of(row.id) + assert [m["id"] for m in card["metrics"]] == ["m1"] and card["metrics"][0]["value"] == 3 + # 取数真跑了:指标输入追到那一条查询快照 + [entry] = card["metrics"][0]["inputs"] + assert entry["via"] == "tool_cell" and entry["artifact"] + + +# ========================================================================== +# 位置引用:nodes.<卡>.metrics[i] 的 i 落在有效数组上 +# ========================================================================== + + +async def test_position_references_follow_the_effective_array(): + """卡上 [m1, m2],只选 m2:有效数组第 0 个是 m2,出口按位置取 [0] 就该拿到 m2 的数。""" + up = await upstream_v1() + graph = with_selection(S.chained_graph(up, version=1), ["m2"]) + out = next(n for n in graph["nodes"] if n["id"] == "out") + out["data"]["config"]["fields"] = [{"name": "销售额", "value": "{{ nodes.card.metrics[0].value }}"}] + row = await run(graph) + assert row.status == "succeeded", row.error + assert float(row.output["销售额"]) == 900.0 # m2 的数,不是全量定义里第 0 个 m1 的 3 + assert (await card_of(row.id))["metrics"][0]["id"] == "m2" + + +# ========================================================================== +# 绑定判定:只看过滤后的真实定义;caliber_from.nodes 改写照常 +# ========================================================================== + + +async def test_binding_and_rename_apply_to_the_selected_metrics(): + up = await upstream_v1() + graph = with_selection(S.chained_graph(up, version=2, local_values=S.NEW, rename={"fetch": "c1_fetch"}), ["m1"]) + row = await run(graph) + assert row.status == "succeeded", row.error + card = await card_of(row.id) + assert [m["id"] for m in card["metrics"]] == ["m1"] and card["metrics"][0]["value"] == 2 # 新定义 2 单 + # 式子里的节点名按 caliber_from.nodes 映射成本地的 c1_fetch + assert card["metrics"][0]["expression"] == "cell(nodes.c1_fetch, 0, 'orders')" + assert card["source"]["nodes"] == {"fetch": "c1_fetch"} and card["source"]["metrics"] == ["m1"] + + +async def test_a_conflicting_sibling_does_not_block_the_selected_metric(): + """m1 说旧口径、m2 说新口径,本地那条 SQL 是旧写法:整卡拦住(说法打架),只选 m1 照常算。""" + metrics = S.card_metrics() # 两条都声明旧口径 + metrics[1]["time_role"] = "payment_time" + metrics[1]["refund_rule"] = "exclude_full_refund" # m2 改成新口径:和 SQL 对不上 + workflow_id = await S.publish(S.graph(values=S.OLD, metrics=metrics), name=f"{OWN_PREFIX}冲突上游") + pin = {"workflow_id": workflow_id, "card": "card"} + + selected = with_selection(S.chained_graph(pin, version=1, rename={"fetch": "c1_fetch"}), ["m1"]) + row = await run(selected) + assert row.status == "succeeded", row.error + card = await card_of(row.id) + assert [m["id"] for m in card["metrics"]] == ["m1"] and card["metrics"][0]["value"] == 3 + + whole = await run(S.chained_graph(pin, version=1, rename={"fetch": "c1_fetch"})) + assert whole.status == "failed" and "对不上" in str(whole.error) + + +# ========================================================================== +# 画布校验:选择的形状;双盲复算认得的指标清单 +# ========================================================================== + + +def _errors(graph: dict) -> list[tuple[str | None, str]]: + return [(i.field, i.message) for i in validate_graph(GraphSpec.model_validate(graph)).issues if i.level == "error"] + + +def _selection_errors(graph: dict) -> list[str]: + return [m for f, m in _errors(graph) if (f or "").startswith("caliber_from.metrics")] + + +def test_schema_validates_the_selection_shape(): + base = S.chained_graph({"workflow_id": "wf-k08", "card": "card"}, version=1) + with_selection(base, ["m1"]) + assert _selection_errors(base) == [] + + for bad in ("m1", ["m1", 2], [""]): + graph = S.chained_graph({"workflow_id": "wf-k08", "card": "card"}, version=1) + with_selection(graph, bad) + assert _selection_errors(graph), bad + + empty = S.chained_graph({"workflow_id": "wf-k08", "card": "card"}, version=1) + with_selection(empty, []) + assert any("空" in m for m in _selection_errors(empty)) + + +def test_dual_check_sees_only_the_selected_metrics(): + """转抄卡带选择时,双盲复算认得的指标就是选中的那些:不在选择里的指标应当报错。""" + def graph_with(selection: list[str]) -> dict: + made = S.chain( + S.node("start", "input"), + S.node("fetch", "tool", tool=S.tool(), args={"sql": "SELECT 1 AS orders, 2 AS amount"}), + S.node("card", "metrics", caliber_from={"workflow_id": "wf-k08", "workflow_version": 1, + "node_id": "card", "metrics": selection}), + S.node("dual", "dual_check", card="card", metrics=["m1"]), + S.node("out", "output", fields=[{"name": "结果", "value": "{{ nodes.dual.text }}"}])) + return made + + assert not [m for f, m in _errors(graph_with(["m1"])) if f == "metrics"] + assert any(f == "metrics" and "不是口径卡" in m for f, m in _errors(graph_with(["m2"]))) + + +# ========================================================================== +# 对账 / 召回:按位置引用时用同一份有效数组 +# ========================================================================== + + +def _pinned(ids: list[str], *, version: int = 1, selection: list[str] | None = None): + """手工拼一个 Pinned(不进库):卡上这些指标,可带一份选择的闭包。""" + from dataclasses import replace + + from app.ledger.derive import Pinned + + metrics = [{"id": i, "name": i, "unit": "", "expression": f"cell(nodes.fetch, 0, '{i}')"} for i in ids] + pin = Pinned(workflow_id="w", workflow_name="W", version=version, node_id="card", level="published", + published=True, retired=False, + card={"id": "card", "type": "metrics", "data": {"label": "卡", "config": {"metrics": metrics}}}, + fetches=(), reads=(), entry_fields=(), defaults={}) + if selection is None: + return pin + + class _Closure: + whole_card = False + + def __init__(self) -> None: + self.metric_ids = tuple(selection) + + return replace(pin, closure=_Closure()) + + +def test_reconcile_and_recall_use_the_effective_array_for_positions(): + from app.engine.nodes.metrics import pinned_effective + from app.ledger import recall, reconcile + + old = _pinned(["m1", "m2"], selection=["m2"]) # 旧版只算 m2 + new = _pinned(["m1", "m2"], version=2) # 新版整卡 + assert [m["id"] for m in pinned_effective(old)] == ["m2"] + assert [m["id"] for m in pinned_effective(new)] == ["m1", "m2"] + # 对账也走同一份解释(卡上没有选择时就是全量定义,行为不变) + assert reconcile.pinned_effective(old) == pinned_effective(old) + + node, meta = recall.recall_card([recall.Pair(old=old, new=new)]) + by_id = {m["id"]: m for m in node["data"]["config"]["metrics"]} + # 有效数组:旧版 m2 在第 0 个、新版 m2 在第 1 个——位置引用必须落在这一份上 + assert by_id["old_0"]["expression"] == "nodes.old_card.metrics[0].value" + assert by_id["new_0"]["expression"] == "nodes.new_card.metrics[1].value" + assert [m["metric"] for m in meta] == ["m2"] + + +def test_recall_without_a_selection_keeps_whole_card_positions(): + """没给选择:位置照全量定义那份,一字不变。""" + from app.ledger import recall + + node, meta = recall.recall_card([recall.Pair(old=_pinned(["m1", "m2"]), new=_pinned(["m1", "m2"], version=2))]) + by_id = {m["id"]: m for m in node["data"]["config"]["metrics"]} + assert by_id["old_1"]["expression"] == "nodes.old_card.metrics[1].value" + assert by_id["new_1"]["expression"] == "nodes.new_card.metrics[1].value" + assert [m["metric"] for m in meta] == ["m1", "m2"] diff --git a/backend/tests/test_caliber_source_snapshot.py b/backend/tests/test_caliber_source_snapshot.py new file mode 100644 index 00000000..825bfb36 --- /dev/null +++ b/backend/tests/test_caliber_source_snapshot.py @@ -0,0 +1,433 @@ +"""K05 的来源侧前置切片:提取时把来源存成不可篡改的工件,引用只认实际进提示的材料。 + +这份文件盯住几件 K05 明确要求、而其它测试没覆盖的事: + +1. **快照可还原,不只是哈希。** 提取时把逐份原文、逐段原文、目录文本按内容寻址存进工件库;草稿 payload 只记引用。 + 读的时候按 id 回读,原文一模一样,哈希对得上(app/core/artifact_store.load 会复验)。 +2. **chunk id 换了,快照照旧读得回来。** 文档被重新切块、段落 id 换了一批,旧草稿记的引用仍指向当初那一份材料。 +3. **可见的引用才核得上。** 材料超限时 fit_material 从后往前丢段落;被丢掉的段落不在提示里,模型引用它也核不上。 + 同一段话在「全量 chunks」下核得上、在「实际进提示的可见 chunks」下核不上。 +4. **每次提示的可见范围有记录。** payload.prompts 逐次记下 visible_chunk_ids、提示词/解析版本、模型、截断情况。 +5. **checkpoint 只是任务恢复,不冒充 B。** checkpoint 里只有「哪些组起草好了」,把它当 payload 读,来源基线仍 + 是 baseline_unknown;来源的还原只走工件。 +6. **旧草稿标记 baseline_unknown。** 没有快照的老草稿不拿当前内容伪造历史基线。 + +模型一律注入假模型(monkeypatch resolve_draft_model),试跑换成假的,测试不发真实请求、不连真实业务库。 +""" +from __future__ import annotations + +import copy +import json +import uuid + +import pytest +from sqlalchemy import delete, select + +from app.core.artifact_store import canonical_json, content_hash, load +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, Chunk, Document, Workflow, WorkflowVersion +from app.ledger import authoring, docdraft, draftplan +from tests.test_ledger_docdraft_api import client, datasource, fake_model, fake_trial # noqa: F401 (fixtures) + +SMALL_ONE = "退款率按已支付订单统计,退款订单不计入。" +SMALL_TWO = "门店维度只保留已支付订单,未支付不进分子分母。" + + +@pytest.fixture(autouse=True) +def _fake_trial(fake_trial): + """本模块的草稿都走接口起草:试跑必须换成假的,不然会去打夹具里不存在的库。 + + (fake_trial 是从别的模块 import 进来的普通夹具,它自带的 autouse 在本模块不生效;这里替本模块的每个用例把它拉起来。)""" + return fake_trial + + +# ========================================================================== +# 夹具:可自定义段落的文档 + 收尾清理 +# ========================================================================== + + +@pytest.fixture +async def docs(): + """按给定的分段建一份文档;收尾删掉它、它的段落、以及测试期间建的草稿/工作流/运行。""" + made: list[str] = [] + + async def make(doc_id: str, chunks: list[tuple[int, str]], *, title: str = "口径.md") -> str: + async with SessionLocal() as session: + session.add(Document(id=doc_id, collection="default", title=title, source=title, + content="".join(content for _, content in chunks), chunk_count=len(chunks))) + for ordinal, content in chunks: + session.add(Chunk(id=f"{doc_id}-{ordinal}", document_id=doc_id, ordinal=ordinal, + content=content)) + await session.commit() + made.append(doc_id) + return doc_id + + yield make + + async with SessionLocal() as session: + drafts = (await session.execute(select(CaliberDraft))).scalars().all() + workflow_ids = [draft.workflow_id for draft in drafts if draft.workflow_id] + workflow_ids += [draft.payload.get("workflow_id") for draft in drafts + if isinstance(draft.payload, dict) and draft.payload.get("workflow_id")] + workflow_ids = list(dict.fromkeys(wid for wid in workflow_ids if wid)) + for draft in drafts: + await session.delete(draft) + if workflow_ids: + await session.execute(delete(WorkflowVersion).where(WorkflowVersion.workflow_id.in_(workflow_ids))) + await session.execute(delete(Workflow).where(Workflow.id.in_(workflow_ids))) + for doc_id in made: + await session.execute(delete(Chunk).where(Chunk.document_id == doc_id)) + row = await session.get(Document, doc_id) + if row is not None: + await session.delete(row) + await session.commit() + + +async def _extract(client, doc: str, source_id: str, **extra) -> dict: + body = (await client.post("/api/ledger/drafts/extract", + json={"documents": [doc], "datasource_id": source_id, **extra})).json() + return body + + +async def _draft(client, draft_id: str) -> dict: + return (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + + +def _reply(chunk_id: str, *, quote: str, name: str = "退款率", sql: str | None = None) -> dict: + """一条指标的回复:引用逐字抄原文。""" + return { + "entry_fields": [], + "sql": sql or "SELECT COUNT(*) AS refund_rate FROM orders", + "metrics": [{ + "id": "m1", "name": name, "synonyms": [], "unit": "%", "decimals": 2, + "expression": "cell(nodes.fetch, 0, 'refund_rate')", + "definition": {"text": "已支付订单里发生退款的比例", + "citations": [{"chunk": chunk_id, "quote": quote}]}, + "open_questions": [], + }], + "open_questions": [], + } + + +# ========================================================================== +# 1. 快照可还原、不可变 +# ========================================================================== + + +async def test_the_first_extraction_persists_a_restorable_source_snapshot(client, docs, datasource, + monkeypatch): + """提取时把原文存进工件库:payload 只有引用,按引用回读,逐份、逐段原文一模一样,哈希对得上。""" + doc = await docs("snap-1", [(0, SMALL_ONE), (1, SMALL_TWO)], title="退款口径.md") + source_id = await datasource() + fake_model(monkeypatch, json.dumps(_reply(f"{doc}-0", quote="退款率按已支付订单统计"), ensure_ascii=False)) + + made = await _draft(client, (await _extract(client, doc, source_id))["draft_id"]) + ref = made["source_snapshot"] + assert ref["version"] == docdraft.SNAPSHOT_VERSION and ref["kind"] == docdraft.SNAPSHOT_KIND + assert ref["chunk_ids"] == [f"{doc}-0", f"{doc}-1"] and ref["documents"] == [doc] + # 引用里的 id 就是规范化内容的 sha256:内容不变,id 不变;内容变了,读的时候复验哈希会当场报错 + assert ref["content_hash"] == ref["artifact_id"] + + snapshot = load(ref["artifact_id"]) + assert snapshot is not None + assert content_hash(canonical_json(snapshot)) == ref["artifact_id"] + assert snapshot["chunks"][f"{doc}-0"]["content"] == SMALL_ONE + assert snapshot["chunks"][f"{doc}-1"]["content"] == SMALL_TWO + assert snapshot["documents"][0]["content"] == SMALL_ONE + SMALL_TWO + assert snapshot["documents"][0]["content_hash"] == content_hash(SMALL_ONE + SMALL_TWO) + assert snapshot["catalog"].strip(), "目录文本也要存:它改了,模型看到的材料和写出的 SQL 就变了" + # 基线状态:有可还原快照 → known(只说明材料还原得出来,不等于字段基线,更不等于业务验证通过) + assert made["source_baseline"] == {"status": "known", "readable": True, "artifact_id": ref["artifact_id"], + "version": docdraft.SNAPSHOT_VERSION, + "chunk_ids": [f"{doc}-0", f"{doc}-1"]} + assert docdraft.source_baseline(made) == made["source_baseline"] + + +async def test_the_snapshot_still_reads_after_the_document_is_rechunked(client, docs, datasource, + monkeypatch): + """重导入会重新切块、换一批 chunk id;旧草稿记的引用仍指向当初那一份材料(按内容寻址,不按名字)。""" + doc = await docs("snap-2", [(0, SMALL_ONE), (1, SMALL_TWO)]) + source_id = await datasource() + fake_model(monkeypatch, json.dumps(_reply(f"{doc}-0", quote="退款率按已支付订单统计"), ensure_ascii=False)) + made = await _draft(client, (await _extract(client, doc, source_id))["draft_id"]) + artifact_id = made["source_snapshot"]["artifact_id"] + + # 文档被重新切块:旧段落删掉,换成三个新 id、顺序和内容也变了 + async with SessionLocal() as session: + await session.execute(delete(Chunk).where(Chunk.document_id == doc)) + for ordinal, content in enumerate([SMALL_TWO, "新加的一段说明。", SMALL_ONE]): + session.add(Chunk(id=f"re-{doc}-{ordinal}", document_id=doc, ordinal=ordinal, content=content)) + await session.commit() + + snapshot = load(artifact_id) + assert snapshot is not None, "旧引用必须还读得回来" + assert set(snapshot["chunks"]) == {f"{doc}-0", f"{doc}-1"}, "当初收进去的段落一个都不能少" + assert snapshot["chunks"][f"{doc}-0"]["content"] == SMALL_ONE + assert snapshot["chunks"][f"{doc}-1"]["content"] == SMALL_TWO + # 草稿里那条指标仍指着当初的段落 id 和原文,不受重新切块影响 + assert made["metrics"][0]["definition"]["citations"][0]["chunk"] == f"{doc}-0" + + +# ========================================================================== +# 2. 引用核对只认实际可见的材料 +# ========================================================================== + + +async def test_a_citation_to_a_truncated_away_chunk_is_not_accepted(client, docs, datasource, monkeypatch): + """材料超限时从后往前丢段落:被丢掉的段落没进提示,模型引用它也核不上,只留能核对的那条指标。""" + tail = "这一段很长,超限时会被整段丢掉。" * 3000 # 六万字,稳稳超过一次提示的上限 + doc = await docs("snap-3", [(0, SMALL_ONE), (1, tail)]) + source_id = await datasource() + reply = _reply(f"{doc}-0", quote="退款率按已支付订单统计", name="退款率") + reply["metrics"].append({**reply["metrics"][0], "id": "m2", "name": "长文里的指标", + "definition": {"text": "引用被丢段的原文", + "citations": [{"chunk": f"{doc}-1", + "quote": "这一段很长,超限时会被整段丢掉"}]}}) + fake_model(monkeypatch, json.dumps(reply, ensure_ascii=False)) + + made = await _draft(client, (await _extract(client, doc, source_id))["draft_id"]) + + assert made["doc_truncated"] is True + assert [m["name"] for m in made["metrics"]] == ["退款率"], "引用不到可见材料的指标不该留下" + assert any(item["name"] == "长文里的指标" and "引用" in item["reason"] for item in made["dropped"]) + # 提示记录里也如实写着:只看得见第一段 + [trace] = [t for t in made["prompts"] if t["purpose"] == "plan"] + assert trace["visible_chunk_ids"] == [f"{doc}-0"] + assert trace["doc_truncated"] is True + assert set(trace["visible_chars"]) == {f"{doc}-0"} + + +def test_normalize_plan_checks_citations_only_against_what_the_model_saw(): + """同一段话:在「全量 chunks」下核得上,在「实际进提示的可见 chunks」下核不上——引用核对以可见范围为准。""" + full = {"c1": {"ordinal": 0, "content": "退款率按已支付订单统计", "document_id": "d"}, + "c2": {"ordinal": 1, "content": "门店维度只保留已支付订单", "document_id": "d"}} + visible = {"c1": full["c1"]} # c2 被截断丢掉了 + raw = {"entry_fields": [], "sql": "SELECT COUNT(*) AS n FROM orders", + "metrics": [{"id": "m1", "name": "退款率", "expression": "cell(nodes.fetch, 0, 'n')", + "definition": {"text": "口径", "citations": [{"chunk": "c2", + "quote": "门店维度只保留已支付订单"}]}}], + "open_questions": []} + + with_visibility, dropped = draftplan.normalize_plan(raw, visible, allowed_tables={"orders"}) + assert with_visibility["metrics"] == [] and dropped and "引用" in dropped[0]["reason"] + + without_visibility, dropped = draftplan.normalize_plan(raw, full, allowed_tables={"orders"}) + assert dropped == [] and [m["name"] for m in without_visibility["metrics"]] == ["退款率"] + + +async def test_plan_groups_reports_the_same_visible_chunks_it_sends_to_the_model(): + """draftplan 自己算材料时,报出来的 visible_chunk_ids 就是真正进提示的那几段(与提示文本一致)。""" + from types import SimpleNamespace + + class Model: + model_name = "visible-model" + + def __init__(self) -> None: + self.messages: list = [] + + async def ainvoke(self, messages): + self.messages = messages + return SimpleNamespace(content='{"groups": [], "open_questions": [], "uncovered": []}') + + first = "第一段:" + "退款率按已支付订单统计。" * 3000 + second = "第二段:" + "门店维度只保留已支付订单。" * 3000 + chunks = {"c1": {"ordinal": 0, "content": first, "document_id": "d"}, + "c2": {"ordinal": 1, "content": second, "document_id": "d"}} + model = Model() + result = await draftplan.plan_groups(None, docs=[], chunks=chunks, tables_text="表 orders", model=model) + sent = "\n".join(str(getattr(message, "content", "")) for message in model.messages) + assert result["visible_chunk_ids"] == ["c1"] and result["doc_truncated"] is True + assert "第一段" in sent and "第二段" not in sent + assert result["prompt_version"] == draftplan.PROMPT_VERSION + assert result["parse_version"] == docdraft.PARSE_VERSION + + +# ========================================================================== +# 3. 提示记录 +# ========================================================================== + + +async def test_every_model_prompt_records_what_it_saw_and_which_versions(client, docs, datasource, + monkeypatch): + """payload.prompts 逐次记下 visible_chunk_ids、模型、提示词/解析版本:历史结果才知道是按哪一版抽的。""" + doc = await docs("snap-4", [(0, SMALL_ONE), (1, SMALL_TWO)]) + source_id = await datasource() + fake_model(monkeypatch, json.dumps(_reply(f"{doc}-0", quote="退款率按已支付订单统计"), ensure_ascii=False)) + + made = await _draft(client, (await _extract(client, doc, source_id))["draft_id"]) + [trace] = made["prompts"] + assert trace["purpose"] == "plan" and trace["round"] == 1 + assert trace["visible_chunk_ids"] == [f"{doc}-0", f"{doc}-1"] + assert trace["model_id"] == "fake-model" + assert trace["prompt_version"] == draftplan.PROMPT_VERSION + assert trace["parse_version"] == docdraft.PARSE_VERSION + assert trace["doc_truncated"] is False and trace["catalog_truncated"] is False + assert trace["visible_chars"][f"{doc}-0"] == len(SMALL_ONE) + + +async def test_the_auxiliary_extract_path_reports_visibility_and_versions(): + """docdraft.extract(辅助路径)也交回可见段落与版本,和主路径一套说法。""" + from types import SimpleNamespace + + class Model: + model_name = "aux-model" + + async def ainvoke(self, _messages): + return SimpleNamespace(content=json.dumps( + {"metrics": [{"name": "退款率", "definition": {"text": "口径", "citations": [ + {"chunk": "c1", "quote": "退款率按已支付订单统计"}]}}]}, ensure_ascii=False)) + + result = await docdraft.extract(None, docs=[{"document_id": "d", "title": "口径.md"}], + chunks={"c1": {"ordinal": 0, "content": SMALL_ONE, "document_id": "d"}}, + model=Model()) + assert result["visible_chunk_ids"] == ["c1"] + assert result["prompt_version"] == docdraft.PROMPT_VERSION + assert result["parse_version"] == docdraft.PARSE_VERSION + assert [m["name"] for m in result["metrics"]] == ["退款率"] + + +# ========================================================================== +# 4. checkpoint 只是任务恢复,不冒充 B +# ========================================================================== + + +async def _run_extract(draft_id: str) -> dict: + """直接调后台起草,试跑换成不启动引擎的桩(不经 HTTP、不建任务)。""" + trial: dict = {} + + async def run_trial(**_kwargs): + return {"run_id": "", "status": "succeeded", "error": ""} + + async def save_trial(_draft_id, value): + trial.update(value or {}) + + def binding(*_args): + return {} + + await authoring.extract(draft_id, run_trial=run_trial, save_trial=save_trial, trial_binding=binding) + return trial + + +async def test_the_checkpoint_is_recovery_only_and_never_masquerades_as_a_baseline(client, docs, datasource, + monkeypatch): + """材料指纹相同的重试接续 checkpoint;checkpoint 只记「哪些组起草好了」,把它当 payload 读仍是 baseline_unknown。""" + doc = await docs("snap-5", [(0, SMALL_ONE), (1, SMALL_TWO)]) + source_id = await datasource() + group = _reply(f"{doc}-0", quote="退款率按已支付订单统计") + calls: list[list[str]] = [] + + async def interrupted(_session, **kwargs): + calls.append(list(kwargs["covered"])) + if len(calls) == 1: + return {"groups": [group], "uncovered": ["门店数"]} + raise RuntimeError("这一轮被打断") + + monkeypatch.setattr(draftplan, "plan_groups", interrupted) + extracted = await _extract(client, doc, source_id) + draft_id = extracted["draft_id"] + await _run_extract(draft_id) + + async with SessionLocal() as session: + row = await session.get(CaliberDraft, draft_id) + payload = copy.deepcopy(row.payload) + # 被打断的那一轮之前,第一组和来源快照都已经写下来了 + assert payload["checkpoint"]["groups"][0]["metrics"][0]["name"] == "退款率" + assert payload["source_snapshot"]["artifact_id"] and payload["source_baseline"]["status"] == "known" + # checkpoint 里只有恢复用的东西:把它当成一份 payload 去读来源基线,只会得到 baseline_unknown + assert set(payload["checkpoint"]) == {"groups"} + assert docdraft.source_baseline(payload["checkpoint"])["status"] == "baseline_unknown" + assert "source_snapshot" not in payload["checkpoint"] + + # 重试:材料没变,checkpoint 里的组接续下去;来源快照仍从这次读到的材料现取(不来自 checkpoint) + second = copy.deepcopy(group) + second["metrics"][0].update(id="m2", name="门店数") + + async def resume(_session, **kwargs): + assert kwargs["covered"] == ["退款率"], "重试要接着上次起草过的地方,不重头再来" + return {"groups": [second], "uncovered": []} + + monkeypatch.setattr(draftplan, "plan_groups", resume) + async with SessionLocal() as session: # 重试会先把草稿置回 drafting(api/ledger 的 retry 就是这样) + row = await session.get(CaliberDraft, draft_id) + row.status = "drafting" + await session.commit() + await _run_extract(draft_id) + async with SessionLocal() as session: + row = await session.get(CaliberDraft, draft_id) + resumed = copy.deepcopy(row.payload) + assert [m["name"] for m in resumed["metrics"]] == ["退款率", "门店数"] + assert resumed["source_snapshot"]["artifact_id"] == payload["source_snapshot"]["artifact_id"] + assert load(resumed["source_snapshot"]["artifact_id"])["chunks"][f"{doc}-1"]["content"] == SMALL_TWO + + +# ========================================================================== +# 5. 旧草稿:baseline_unknown,不拿当前值伪造历史 +# ========================================================================== + + +async def test_an_old_draft_without_a_snapshot_reads_as_baseline_unknown(client, docs): + """保存来源快照之前起草的草稿没有引用:如实标记 baseline_unknown,不能拿它现在的内容当历史基线。""" + draft_id = f"old-{uuid.uuid4().hex[:10]}" + old_payload = {"metrics": [{"id": "m1", "name": "旧指标", "expression": "cell(nodes.fetch, 0, 'n')"}], + "sql": "SELECT 1 AS n", "version": 1, "workflow_id": None} + async with SessionLocal() as session: + session.add(CaliberDraft(id=draft_id, title="老草稿", status="path_pending", + payload=copy.deepcopy(old_payload))) + await session.commit() + + async with SessionLocal() as session: + stored = (await session.get(CaliberDraft, draft_id)).payload + baseline = docdraft.source_baseline(stored) + assert baseline["status"] == "baseline_unknown" and "无法还原" in baseline["reason"] + assert "artifact_id" not in baseline + + body = await _draft(client, draft_id) + assert body["status"] == "path_pending" and body["metrics"][0]["name"] == "旧指标" + # 老草稿里根本没有快照,也没有凭空补一条:当前内容照旧显示,但它不是「上次被接受的导入值」。 + # 读接口如实给出 baseline_unknown(没有快照本身就是要说的话,不能让客户端从「缺字段」去猜) + assert "source_snapshot" not in body + assert body["source_baseline"]["status"] == "baseline_unknown" + assert "无法还原" in body["source_baseline"]["reason"] and "artifact_id" not in body["source_baseline"] + assert docdraft.source_baseline(body)["status"] == "baseline_unknown" + + +async def test_a_snapshot_is_not_invented_for_a_draft_without_one(client, docs, datasource, monkeypatch): + """新草稿照常记快照;同一批材料被再次读取时快照不变(按内容寻址,同一份材料只存一份、id 相同)。""" + doc = await docs("snap-6", [(0, SMALL_ONE)]) + source_id = await datasource() + fake_model(monkeypatch, json.dumps(_reply(f"{doc}-0", quote="退款率按已支付订单统计"), ensure_ascii=False)) + first = await _draft(client, (await _extract(client, doc, source_id))["draft_id"]) + + fake_model(monkeypatch, json.dumps(_reply(f"{doc}-0", quote="退款率按已支付订单统计", + name="退款率(第二份)"), ensure_ascii=False)) + second = await _draft(client, (await _extract(client, doc, source_id))["draft_id"]) + + assert first["source_snapshot"]["artifact_id"] == second["source_snapshot"]["artifact_id"] + assert docdraft.source_baseline(second)["status"] == "known" + + +# ========================================================================== +# 6. 装快照失败时如实说「没有基线」,不假装有 +# ========================================================================== + + +async def test_a_snapshot_that_cannot_be_stored_is_reported_as_baseline_unknown(client, docs, datasource, + monkeypatch): + """落工件失败(磁盘/库出错)不让整份草稿失败,但也绝不假装有基线:source_snapshot 为空、状态 unknown。""" + import app.core.artifact_store as store + + doc = await docs("snap-7", [(0, SMALL_ONE)]) + source_id = await datasource() + fake_model(monkeypatch, json.dumps(_reply(f"{doc}-0", quote="退款率按已支付订单统计"), ensure_ascii=False)) + + async def broken(*_args, **_kwargs): + raise OSError("磁盘满了") + + # _capture_source 在函数里 `from app.core.artifact_store import put_json`,换掉模块属性就换掉了它 + monkeypatch.setattr(store, "put_json", broken) + + made = await _draft(client, (await _extract(client, doc, source_id))["draft_id"]) + assert made["status"] in ("ready", "questions_open"), made.get("error") + assert made["workflow_id"], "快照存不下不该把草稿判死:图和试跑照旧" + assert made["source_snapshot"] is None + assert made["source_baseline"]["status"] == "baseline_unknown" diff --git a/backend/tests/test_caliber_validation_real_chain.py b/backend/tests/test_caliber_validation_real_chain.py new file mode 100644 index 00000000..84b104bb --- /dev/null +++ b/backend/tests/test_caliber_validation_real_chain.py @@ -0,0 +1,199 @@ +"""K05 的真实链路:真引擎、真 SQLite 数据源、真 HTTP —— 试运行 → matched → 认证审阅 → verified → 发布。 + +**这份文件不换 `_trial_metrics` / `_trial_queries` 的桩**:走的是「起草出来的那种口径卡 + 真跑一次探针图」的完整 +路径,考的就是「真实运行的证据能不能被验证记录认出来」。以前的阻断点正是这里:界面那份指标投影里没有取数节点, +而验证记录按节点把指标对到查询快照上——对不上就一律判不了形状,matched / verified / 发布永远到不了。 + +覆盖的形状(都是真跑出来的):恰好一行(matched)、多行(标量取数有歧义)、空结果(没有可取的数)。 + +发布那一步证明的是:**认证审阅过的这条记录,绑的是被发布的那一版定义与绑定**(发布不改图,所以记录照旧覆盖)。 +""" +from __future__ import annotations + +import copy +import uuid + +import pytest +from sqlalchemy import delete, select + +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, Run, Workflow, WorkflowVersion +from app.engine.runner import run_manager +from app.ledger import validation +from tests import ledger_samples as S +from tests.test_caliber_draft_reads import attached_draft # noqa: F401 - 帮手共用 +from tests.test_ledger_docdraft_api import client # noqa: F401 - fixture 和别的口径用例共用 + +#: 这次起草的口径:九月一号到八号,契约数据集里 SUM(amount) = 170.5(独立期望照这个写,不照这次运行的结果抄) +EXPECTED = 170.5 +WINDOW = {"start": "2026-09-01", "end": "2026-09-08"} + +#: 这一份文件自己建的工作流(收尾时连草稿、版本、记录一起清掉) +OWN_PREFIX = "K05 真实链路 " + + +def real_graph(sql: str, *, fields: list[dict] | None = None) -> dict: + """一份像**起草产物**那样已接管的图:入口 → 取数 → 口径卡(标量契约)。 + + 契约是照着 app/ledger/draftplan 建图时写的来(`contract: {"shape": "scalar"}`):起草出来的指标都声明标量, + 多行和空结果才会被引擎和验证记录判成形状不符。 + """ + return S.chain( + S.node("start", "input", fields=fields if fields is not None else [ + {"name": "start", "required": True}, {"name": "end", "required": True}]), + S.node("fetch", "tool", tool=S.tool(), args={"sql": sql}), + S.node("card", "metrics", caliber="周销售", caliber_version="v1", + metrics=[{"id": "gmv", "name": "销售额", "unit": "元", "decimals": 2, + "expression": "cell(nodes.fetch, 0, 'gmv')", "contract": {"shape": "scalar"}}])) + + +@pytest.fixture(autouse=True) +async def engine_and_source(tmp_path): + await run_manager.setup() + await S.fresh_source(tmp_path / "shop.db") + yield + await run_manager.shutdown() + async with SessionLocal() as session: + ids = list((await session.execute( + select(Workflow.id).where(Workflow.name.like(f"{OWN_PREFIX}%")))).scalars()) + # 试运行留下的运行行:工作流删掉之后 workflow_id 会被置空,按当时记下的工作流名清掉 + await session.execute(delete(Run).where(Run.workflow_name.like(f"{OWN_PREFIX}%"))) + if ids: + await session.execute(delete(CaliberDraft).where(CaliberDraft.workflow_id.in_(ids))) + await session.execute(delete(WorkflowVersion).where(WorkflowVersion.workflow_id.in_(ids))) + await session.execute(delete(Workflow).where(Workflow.id.in_(ids))) + await session.commit() + + +async def real_draft(*, sql: str | None = None) -> dict: + """一份像起草产物那样已接管、指向真实数据源的草稿(图里就一张口径卡 + 一次取数)。""" + made = await attached_draft(graph=real_graph(sql or S.TEMPLATE), + payload={"sql": S.TEMPLATE, "entry_fields": [{"name": "start"}, {"name": "end"}]}) + async with SessionLocal() as session: + workflow = await session.get(Workflow, made["workflow_id"]) + workflow.name = f"{OWN_PREFIX}{uuid.uuid4().hex[:6]}" + await session.commit() + return made + + +async def validations(client, draft_id: str) -> dict: + return (await client.get(f"/api/ledger/drafts/{draft_id}/validations")).json() + + +async def repoint(client, body: dict, sql: str) -> int: + """把这份草稿的取数换成另一句(画布那种改法),返回新版本号。""" + saved = await client.patch(f"/api/workflows/{body['workflow_id']}", + json={"graph": real_graph(sql), "expected_revision": body["revision"]}) + assert saved.status_code == 200, saved.text + return saved.json()["version"] + + +async def test_a_real_trial_matches_confirms_verifies_and_survives_publication(client): + """真跑一次:独立期望对得上 → matched;认证审阅(全指标)→ verified;发布的那一版和记录绑的是同一份依据。""" + body = await real_draft() + done = await client.post(f"/api/ledger/drafts/{body['id']}/trial", + json={"inputs": WINDOW, + "expect": {"metrics": {"gmv": EXPECTED}, "source": "fixture", + "sample_id": "sept-2026", "sample_version": "1"}}) + assert done.status_code == 200, done.text + trial = done.json() + assert trial["status"] == "succeeded", trial.get("error") + # 真实运行交回的指标值就是契约数据集里那一份(不是桩) + assert float(trial["metrics"][0]["value"]) == EXPECTED + assert "node_id" not in trial["metrics"][0] # 关联网不放给用户看的响应 + + record = trial["validation"]["record"] + assert record["status"] == "matched", record["problems"] + assert record["problems"] == [] + assert record["metric_ids"] == ["gmv"] + assert record["expected"]["metrics"] == {"gmv": EXPECTED} + assert record["actual"]["gmv"]["value"] == EXPECTED + assert record["actual"]["gmv"]["rows"] == 1 and record["actual"]["gmv"]["shape_ok"] is True + assert record["actual"]["gmv"]["ok"] is True + assert record["covers_current"] is True + + # 对得上不等于批准:还没有审阅 + listed = await validations(client, body["id"]) + assert listed["summary"]["status"] == "matched" and listed["summary"]["verdict"] == "unverified" + + confirmed = await client.post( + f"/api/ledger/drafts/{body['id']}/validations/{record['id']}/review", + json={"decision": "confirmed", "note": "按独立算出来的九月预期核过"}, headers={"X-Actor": "alice"}) + assert confirmed.status_code == 201, confirmed.text + review = confirmed.json()["record"]["review"] + assert review["decision"] == "confirmed" and review["scope"] == ["gmv"] + listed = await validations(client, body["id"]) + assert listed["summary"]["verdict"] == "verified" and listed["summary"]["unconfirmed"] == [] + + # 发布:这一版就是被审阅过的那一份定义与绑定;发布不改图,所以记录照旧覆盖 + published = await client.post(f"/api/workflows/{body['workflow_id']}/publish", + json={"level": "published"}) + assert published.status_code == 200 and published.json()["ok"], published.text + detail = (await client.get(f"/api/ledger/drafts/{body['id']}")).json() + assert detail["validation"]["verdict"] == "verified" + assert detail["validation"]["covers_current"] is True + async with SessionLocal() as session: + row = (await session.execute(select(WorkflowVersion).where( + WorkflowVersion.workflow_id == body["workflow_id"], + WorkflowVersion.version == body["revision"]))).scalar_one() + assert row.level == "published" + # 被发布的这份图和记录里的定义依据是同一份(发布依据和验证依据对得上) + assert validation.definition_hash(row.graph, "card") == record["definition_hash"] + assert (await validations(client, body["id"]))["records"][0]["id"] == record["id"] + + +async def test_a_real_multi_row_result_does_not_pass_on_the_first_row(client): + """多行形状(真跑):标量指标取回两行时不能只看第一行,记 mismatched 并把「恰好一行」说清楚。""" + body = await real_draft() + sql = ("SELECT o.region AS gmv FROM orders o WHERE o.status = 'paid' " + "AND o.paid_at >= '{{ input.start }}' AND o.paid_at < '{{ input.end }}'") + version = await repoint(client, body, sql) + done = await client.post(f"/api/ledger/drafts/{body['id']}/trial", + json={"inputs": WINDOW, "expect": {"metrics": {"gmv": EXPECTED}}}) + assert done.status_code == 200, done.text + trial = done.json() + assert trial["status"] == "succeeded", trial.get("error") + [query] = trial["queries"] + assert query["total_rows"] > 1 + record = trial["validation"]["record"] + assert record["version"] == version + assert record["status"] == "mismatched", record["problems"] + assert record["actual"]["gmv"]["rows"] > 1 and record["actual"]["gmv"]["shape_ok"] is False + assert any("恰好一行" in problem for problem in record["problems"]) + + +async def test_a_real_empty_result_never_counts_as_a_pass(client): + """空结果形状(真跑):查询一行都没有时(0 行)不能当作取到了值,记录不会是 matched。""" + body = await real_draft() + # 非聚合取数:窗口里没有行时结果就是 0 行(聚合在 0 行上仍交回一行 NULL,另按「没有值」判) + await repoint(client, body, "SELECT o.region AS gmv FROM orders o WHERE 1 = 0 " + "AND o.paid_at >= '{{ input.start }}' AND o.paid_at < '{{ input.end }}'") + done = await client.post(f"/api/ledger/drafts/{body['id']}/trial", + json={"inputs": WINDOW, "expect": {"metrics": {"gmv": EXPECTED}}}) + assert done.status_code == 200, done.text + trial = done.json() + record = trial["validation"]["record"] + assert record is not None + assert record["status"] != "matched" + actual = record["actual"].get("gmv") or {} + if record["status"] == "mismatched": + assert actual.get("rows") == 0 and actual.get("shape_ok") is False + assert any("空结果" in problem or "0 行" in problem for problem in record["problems"]) + else: + # 这条取数让口径卡算不出值(取不到第一格)时,整个试运行就是 failed:同样不能算通过 + assert record["status"] == "failed" + assert any("没有成功" in problem or "没有结果" in problem for problem in record["problems"]) + + +async def test_a_real_aggregate_over_no_rows_is_not_a_pass(client): + """聚合查询在空窗口上仍交回一行 NULL:有行、没有值,也不算通过(不能拿 NULL 当 0)。""" + body = await real_draft() + await repoint(client, body, "SELECT SUM(amount) AS gmv FROM orders WHERE 1 = 0 " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") + done = await client.post(f"/api/ledger/drafts/{body['id']}/trial", + json={"inputs": WINDOW, "expect": {"metrics": {"gmv": EXPECTED}}}) + assert done.status_code == 200, done.text + record = done.json()["validation"]["record"] + assert record["status"] == "mismatched", record["problems"] + assert record["actual"]["gmv"]["value"] is None + assert any("没有取到值" in problem for problem in record["problems"]) diff --git a/backend/tests/test_caliber_validation_records.py b/backend/tests/test_caliber_validation_records.py new file mode 100644 index 00000000..d2447934 --- /dev/null +++ b/backend/tests/test_caliber_validation_records.py @@ -0,0 +1,771 @@ +"""K05 的验证记录与最小审阅:追加存储、绑定定义/绑定依据、独立期望、覆盖判断、认证审阅。 + +这份文件盯住任务书 4.8 与 E05/E07/E15/R04/R05/R06/R07 的硬要求: + +1. **没有期望只能记 observed,不能 pass。** 试跑成功不等于验证通过:没有独立期望时状态是 observed,证据不足是 + unverified,只有「有期望、逐条对得上」才是 matched——而 matched 也只是「这一次对得上」,不等于批准。 +2. **独立期望能做全指标、全约定形状的比较。** 期望要逐条给全卡指标(漏一条拒);声明成标量的指标必须恰好一行, + 空结果与多行**不能只看第一行**(R04/R05)。比较是原值比较、不做隐式舍入(R06)。 +3. **覆盖是读的时候按指纹现算的。** 定义、绑定或取数语义(含 SQL)变了,旧记录不再覆盖当前版本(covers_current + false);把一段没验证过的业务描述删掉不会让旧的验证/审阅升级成通过(E15/R07)。 +4. **交错结束的两次试跑各留一条记录。** 晚到的旧试跑替换不了当前 trial 指针,但它自己那一行一定要落下(E07)。 +5. **审阅绑定认证主体。** 审批人只来自服务端身份:请求体里写 actor 回 422,没有可记的主体回 409;决定绑定所审 + 记录的依据,样例匹配不会自动变成批准。 + +模型一律注入假模型、试跑换成假的(结果证据用桩替代);走的是真实 HTTP 接口,不连真实业务库。 +""" +from __future__ import annotations + +import copy +import json +import re +import uuid + +import pytest +from sqlalchemy import delete, select + +from app.api import ledger as api_ledger +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, CaliberReviewDecision, CaliberValidationRecord, Workflow +from app.ledger import validation +from tests.test_caliber_field_baseline import accepted_draft # noqa: F401 - 起草帮手和夹具共用 +from tests.test_ledger_docdraft_api import ( # noqa: F401 - fixture 和起草用例共用 + client, datasource, documents, extract, fake_model, fake_trial, groups_reply, plan_reply, +) + + +def plant_evidence(monkeypatch, *, value=2, values=None, rows=1, masked=False, status="ok", semantic=False, + metric_ids=("m1",), node="fetch", nodes=None): + """把这次试运行交回的证据换成桩:指标 + 每个取数节点一条查询快照。 + + 值、行数从这里给,用来构造空结果、多行、遮罩这些反例;`values` 可以逐条指标给不同的值,`nodes` 给 + metric_id → 取数节点(多指标卡的两个节点各查一次)。semantic=True 模拟引擎判出的 + 「业务描述和取数条件的关系还没被证明」(semantic_unverified)。""" + per_metric = dict(values or {}) + per_node = dict(nodes or {}) + + async def metrics(run_id: str) -> list[dict]: + out: list[dict] = [] + for metric_id in metric_ids: + reported = None if (masked or rows == 0) else per_metric.get(metric_id, value) + item = {"id": metric_id, "name": f"指标 {metric_id}", "unit": "%", "value": reported, + "status": status, "rendered": reported, "node_id": per_node.get(metric_id, node)} + if masked: + item.update(masked=True, quality={"status": "unknown", "checks": [ + {"code": "masked", "status": "unknown", "detail": "指标值已隐藏,不能在此验证"}]}) + else: + checks = [] + if semantic: + checks.append({"code": "semantic_definition", "status": "unknown", + "detail": "业务描述与取数条件的一致性仍需审阅"}) + item["quality"] = {"status": "unknown" if checks else "pass", "checks": checks} + out.append(item) + return out + + async def queries(run_id: str) -> list[dict]: + wanted = list(dict.fromkeys(per_node.get(mid, node) for mid in metric_ids)) + return [{"node_id": node_id, "tool": "db_query", "source": "shop", "columns": ["rate"], + "rows": [], "total_rows": rows, "truncated": False, "masked": [], + "source_truncated": False, "preview_truncated": False} for node_id in wanted] + + async def links(run_id: str) -> tuple[dict[str, str], list[dict]]: + """指标 → 取数快照的关联(真实运行里由 _trial_metric_links 从封存口径卡认出来):桩按 nodes 给。""" + wanted = list(dict.fromkeys(per_node.get(mid, node) for mid in metric_ids)) + return ({mid: per_node.get(mid, node) for mid in metric_ids}, + [{"key": node_id, "node_id": node_id, "total_rows": rows, "truncated": False} + for node_id in wanted]) + + monkeypatch.setattr(api_ledger, "_trial_metrics", metrics) + monkeypatch.setattr(api_ledger, "_trial_queries", queries) + monkeypatch.setattr(api_ledger, "_trial_metric_links", links) + + +def nodes_of(metrics: list[dict]) -> dict[str, str]: + """每条指标读哪个取数节点(从表达式里取):桩证据按它对到查询上,多指标卡两个节点各一条快照。""" + out: dict[str, str] = {} + for metric in metrics if isinstance(metrics, list) else []: + found = re.search(r"nodes\.([\w-]+)", str((metric or {}).get("expression") or "")) + if isinstance(metric, dict) and metric.get("id") and found: + out[str(metric["id"])] = found.group(1) + return out + + +async def run_trial(client, draft_id: str, *, expect=None, inputs=None) -> dict: + body: dict = {"inputs": inputs or {}} + if expect is not None: + body["expect"] = expect + return (await client.post(f"/api/ledger/drafts/{draft_id}/trial", json=body)).json() + + +@pytest.fixture(autouse=True) +def _fake_trial(fake_trial): + """本模块的草稿都走接口起草:试跑必须换成假的,不然会去打夹具里不存在的库。""" + return fake_trial + + +async def validations(client, draft_id: str) -> dict: + return (await client.get(f"/api/ledger/drafts/{draft_id}/validations")).json() + + +def baseline_metrics(one: dict, *, name: str = "订单金额", mid: str = "m2", column: str = "gmv") -> dict: + """第二组指标:改 id / 名字 / 表达式 / SQL,用来构造「一张卡两条指标」的全指标比较。""" + two = copy.deepcopy(one) + two["metrics"][0].update(id=mid, name=name, expression=f"cell(nodes.fetch, 0, '{column}')") + two["sql"] = f"SELECT SUM(amount) AS {column} FROM orders WHERE store = '{{{{ input.store }}}}'" + return two + + +# ========================================================================== +# 1. 没有期望只记 observed +# ========================================================================== + + +async def test_a_trial_without_an_expectation_is_only_observed(client, documents, datasource, monkeypatch): + """自动试跑没有独立期望:记录照落,但状态是 observed——跑了、取了数,一个字也不能说「通过」。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + listed = await validations(client, made["id"]) + assert len(listed["records"]) == 1 # 同一次试跑保存两次也只落一行 + [record] = listed["records"] + assert record["status"] == "observed" and record["expected"] is None + assert record["covers_current"] is True + assert record["definition_hash"] and record["semantic_hash"] + assert record["method"]["version"] == validation.METHOD_VERSION + assert any("没有独立期望" in problem for problem in record["problems"]) + assert listed["summary"]["verdict"] == "observed" and listed["summary"]["review"] is None + assert "不能算验证通过" in listed["summary"]["reason"] + + # 试跑接口里也带上这条记录,并且同样不说通过 + trial = (await client.get(f"/api/ledger/drafts/{made['id']}/trial")).json() + assert trial["validation"]["record"]["id"] == record["id"] + assert trial["validation"]["covers_current"] is True + detail = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert detail["validation"]["verdict"] == "observed" + + +# ========================================================================== +# 2. 固定期望:对得上 / 对不上 / 空结果 / 多行 +# ========================================================================== + + +async def test_a_fixed_fixture_expectation_decides_matched_or_mismatched(client, documents, datasource, + monkeypatch): + """显式固定 fixture 期望:对得上记 matched,对不上记 mismatched;但它只是「这一次对得上」,不是批准。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + plant_evidence(monkeypatch, value=2, rows=1) + + ok = await run_trial(client, made["id"], expect={"metrics": {"m1": 2}, "source": "fixture", + "sample_id": "oct-2026", "sample_version": "1", + "note": "独立算出来的十月预期"}) + assert ok["status"] == "succeeded", ok + record = ok["validation"]["record"] + assert record["status"] == "matched" and record["problems"] == [] + assert record["expected"]["source"] == "fixture" + assert record["expected"]["metrics"] == {"m1": 2} + assert record["actual"]["m1"]["value"] == 2 and record["actual"]["m1"]["ok"] is True + assert record["actual"]["m1"]["rows"] == 1 and record["actual"]["m1"]["shape"] == "scalar" + assert record["sample"] == {"id": "oct-2026", "version": "1"} + assert record["covers_current"] is True and record["inputs_hash"] + + # 对得上也不等于批准:摘要仍是 unverified,并且这么说 + listed = await validations(client, made["id"]) + assert listed["summary"]["status"] == "matched" + assert listed["summary"]["verdict"] == "unverified" + assert "不等于正式批准" in listed["summary"]["reason"] + + bad = await run_trial(client, made["id"], expect={"metrics": {"m1": 3}, "source": "fixture"}) + record = bad["validation"]["record"] + assert record["status"] == "mismatched" + assert record["actual"]["m1"]["ok"] is False + assert any("对不上" in problem and "3" in problem for problem in record["problems"]) + assert (await validations(client, made["id"]))["summary"]["verdict"] == "mismatched" + + +async def test_an_empty_result_is_not_a_pass_and_multi_row_does_not_read_the_first_row( + client, documents, datasource, monkeypatch): + """空结果与多行都不是「取第一行就对」:声明成标量的指标要恰好一行(R04/R05)。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + + plant_evidence(monkeypatch, value=None, rows=0) + empty = await run_trial(client, made["id"], expect={"metrics": {"m1": 2}}) + record = empty["validation"]["record"] + assert record["status"] == "mismatched" and record["actual"]["m1"]["rows"] == 0 + assert any("空结果" in problem or "0 行" in problem for problem in record["problems"]) + + # 第一行正好等于期望,但查询回来 3 行:标量取数有歧义,不能算通过 + plant_evidence(monkeypatch, value=2, rows=3) + multi = await run_trial(client, made["id"], expect={"metrics": {"m1": 2}}) + record = multi["validation"]["record"] + assert record["status"] == "mismatched" and record["actual"]["m1"]["value"] == 2 + assert record["actual"]["m1"]["rows"] == 3 + assert any("恰好一行" in problem for problem in record["problems"]) + + # 值被遮罩:判不了,记 unverified(不是 matched、也不是 mismatched) + plant_evidence(monkeypatch, value=2, rows=1, masked=True) + hidden = await run_trial(client, made["id"], expect={"metrics": {"m1": 2}}) + record = hidden["validation"]["record"] + assert record["status"] == "unverified" and record["actual"]["m1"]["masked"] is True + assert any("遮罩" in problem for problem in record["problems"]) + + +async def test_a_semantic_gap_is_recorded_and_never_becomes_a_pass_by_itself(client, documents, datasource, + monkeypatch): + """R07:语义说明没被证明是一处待确认的缺口,照实记在记录里;它自己不会让任何东西算「通过」。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + plant_evidence(monkeypatch, value=2, rows=1, semantic=True) + trial = await run_trial(client, made["id"], expect={"metrics": {"m1": 2}, "source": "fixture"}) + record = trial["validation"]["record"] + assert record["status"] == "matched" and record["actual"]["m1"]["ok"] is True + assert record["actual"]["m1"]["semantic_unverified"] is True + assert not any("语义" in problem for problem in record["problems"]) # 不是比较结论,不并进 problems + + listed = await validations(client, made["id"]) + assert listed["summary"]["semantic_gaps"] == ["m1"] + assert listed["summary"]["status"] == "matched" + assert listed["summary"]["verdict"] == "unverified" # 没有认证审阅就还是不算通过 + + # 人工确认之后才算 verified,但语义缺口仍旧写在结论里(「已确认」不等于「这段描述被证明」) + confirmed = await client.post(f"/api/ledger/drafts/{made['id']}/validations/{record['id']}/review", + json={"decision": "confirmed"}, headers={"X-Actor": "alice"}) + assert confirmed.status_code == 201, confirmed.text + listed = await validations(client, made["id"]) + assert listed["summary"]["verdict"] == "verified" + assert listed["summary"]["semantic_gaps"] == ["m1"] + assert "语义说明仍待人工确认" in listed["summary"]["reason"] + + +async def test_a_trial_that_never_ran_is_recorded_as_unverified(client, documents, datasource, monkeypatch): + """停在 needs_input 的试跑(一条 SQL 都没发):记录照落,状态是 unverified,并明说没有可比较的实际结果。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + + async def waiting(*, draft_id, workflow_id, graph, values, started_by, entry_fields=(), version=1): + return {**api_ledger._trial_binding(version, graph, values), "trial_id": "wait-1", "run_id": "", + "status": "needs_input", "error": "缺少必填输入:start"} + + monkeypatch.setattr(api_ledger, "_run_trial", waiting) + await run_trial(client, made["id"], expect={"metrics": {"m1": 2}}) + listed = await validations(client, made["id"]) + newest = listed["records"][0] + assert newest["status"] == "unverified" and newest["run_id"] == "" and newest["trial_id"] == "wait-1" + assert newest["expected"]["metrics"] == {"m1": 2} + assert any("没有成功" in problem for problem in newest["problems"]) + assert listed["summary"]["verdict"] == "unverified" + + +async def test_the_expectation_must_cover_the_whole_card_and_use_a_known_source(client, documents, datasource, + monkeypatch): + """全指标比较:期望要逐条给全卡指标;来源只能是三种之一。不合规在发起运行之前回 422。""" + doc = await documents("val-multi-" + uuid.uuid4().hex[:8]) + source = await datasource() + one = json.loads(plan_reply(f"{doc}-2")) + fake_model(monkeypatch, groups_reply(one, baseline_metrics(one))) + body = await extract(client, doc, source) + draft_id = body["draft_id"] + made = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + assert sorted(m["id"] for m in made["metrics"]) == ["m1", "m2"] + + partial = await client.post(f"/api/ledger/drafts/{draft_id}/trial", + json={"inputs": {}, "expect": {"metrics": {"m1": 2}}}) + assert partial.status_code == 422 and "m2" in partial.text + + stranger = await client.post(f"/api/ledger/drafts/{draft_id}/trial", + json={"inputs": {}, "expect": {"metrics": {"nope": 2}}}) + assert stranger.status_code == 422 and "nope" in stranger.text + + invented = await client.post(f"/api/ledger/drafts/{draft_id}/trial", + json={"inputs": {}, "expect": {"metrics": {"m1": 2, "m2": 3}, + "source": "model_said_so"}}) + assert invented.status_code == 422 and "human_confirmed" in invented.text + + plant_evidence(monkeypatch, value=2, rows=1) + whole = await client.post(f"/api/ledger/drafts/{draft_id}/trial", + json={"inputs": {}, "expect": {"metrics": {"m1": 2, "m2": 3}, + "source": "independent_computation"}}) + assert whole.status_code == 200, whole.text + record = whole.json()["validation"]["record"] + assert record["metric_ids"] == ["m1", "m2"] + assert record["actual"]["m1"]["ok"] is True + # m2 这一次没有交回结果(桩只造了 m1):判不了,不能算通过 + assert record["actual"]["m2"]["status"] == "missing" and record["actual"]["m2"]["ok"] is None + assert record["status"] == "unverified" + + +# ========================================================================== +# 3. 覆盖判断与 E15/R07:删掉没验证过的描述不会升级成通过 +# ========================================================================== + + +async def test_deleting_a_semantic_field_does_not_keep_an_old_verification_verified( + client, documents, datasource, monkeypatch): + """确认过的一次验证,在定义被改(删掉一段业务描述)之后不再覆盖当前版本,也不能拿它当新定义的批准。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + draft_id = made["id"] + plant_evidence(monkeypatch, value=2, rows=1) + trial = await run_trial(client, draft_id, expect={"metrics": {"m1": 2}, "source": "fixture"}) + record_id = trial["validation"]["record"]["id"] + + confirmed = await client.post(f"/api/ledger/drafts/{draft_id}/validations/{record_id}/review", + json={"decision": "confirmed", "note": "看过独立样例"}, + headers={"X-Actor": "alice"}) + assert confirmed.status_code == 201, confirmed.text + listed = await validations(client, draft_id) + assert listed["summary"]["verdict"] == "verified" + + # 删掉「口径说明」这段没被取数证明过的业务描述:定义指纹变了 + revision = (await client.get(f"/api/ledger/drafts/{draft_id}")).json()["revision"] + removed = await client.patch(f"/api/ledger/drafts/{draft_id}", json={ + "operations": [{"op": "remove", "metric_id": "m1", "path": "/definition/text"}], + "expected_revision": revision, "request_id": "drop-semantic-1"}) + assert removed.status_code == 200, removed.text + + after = await validations(client, draft_id) + assert after["summary"]["covers_current"] is False and after["summary"]["verdict"] == "stale" + # 旧记录和旧审阅都还在(历史可追),但都明说不再覆盖当前版本 + old = next(item for item in after["records"] if item["id"] == record_id) + assert old["status"] == "matched" and old["covers_current"] is False + assert old["review"]["decision"] == "confirmed" and old["review"]["covers_current"] is False + assert old["review"]["actor"] == "alice" + # 摘要里带上的是「覆盖不了当前版本」的结论,不是拿旧的 confirmed 当通过 + assert after["summary"]["verdict"] != "verified" + assert after["summary"]["covers_current"] is False + assert (await client.get(f"/api/ledger/drafts/{draft_id}")).json()["validation"]["verdict"] == "stale" + + +async def test_a_sql_change_alone_stops_the_old_record_from_covering(client, documents, datasource, monkeypatch): + """取数 SQL 改了(定义没动)也算对新版本不覆盖:覆盖看的不只是定义指纹;画布编辑也不推进 B。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + listed = await validations(client, made["id"]) + assert listed["summary"]["covers_current"] is True + before_baseline = listed["field_baseline"] + assert before_baseline["status"] == "known" + async with SessionLocal() as session: + workflow = await session.get(Workflow, made["workflow_id"]) + graph = copy.deepcopy(workflow.graph) + revision = workflow.version + fetch = next(node for node in graph["nodes"] if node["id"] == "fetch") + fetch["data"]["config"]["args"]["sql"] = "SELECT COUNT(*) * 2.0 AS refund_rate FROM orders " \ + "WHERE status = 'paid' AND store = '{{ input.store }}'" + saved = await client.patch(f"/api/workflows/{made['workflow_id']}", + json={"graph": graph, "expected_revision": revision}) + assert saved.status_code == 200, saved.text + after = await validations(client, made["id"]) + assert after["summary"]["covers_current"] is False and after["summary"]["verdict"] == "stale" + # 画布上的改动只动 L:字段基线 B 的引用和值一个字没变 + assert after["field_baseline"] == before_baseline + + +# ========================================================================== +# 4. 交错结束的两次试跑:两条记录都留下(E07) +# ========================================================================== + + +async def test_interleaved_trials_each_leave_their_own_record(client, documents, datasource, monkeypatch): + """晚到的旧试跑替换不了当前 trial 指针,但它自己那一行一定要落下:新旧两条都可追踪。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + draft_id = made["id"] + async with SessionLocal() as session: + workflow = await session.get(Workflow, made["workflow_id"]) + graph_v1 = copy.deepcopy(workflow.graph) + metrics = copy.deepcopy(made["metrics"]) + metrics[0]["unit"] = "%" # 定义变了一处 → 新版本 + changed = await client.patch(f"/api/ledger/drafts/{draft_id}", + json={"metrics": metrics, "expected_revision": made["revision"]}) + assert changed.status_code == 200, changed.text + + plant_evidence(monkeypatch, value=2, rows=1) + newest = await run_trial(client, draft_id) + # 旧那一次(还对着 v1 的图)晚到:指针不换,记录照落 + late = {**api_ledger._trial_binding(1, graph_v1, {}), "trial_id": "late-1", "run_id": "", + "status": "succeeded", "error": ""} + assert await api_ledger._save_trial(draft_id, late) is False + + detail = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + assert detail["trial"]["trial_id"] == newest["trial_id"] # 当前指针还是新的那一次 + listed = await validations(client, draft_id) + by_trial = {record["trial_id"]: record for record in listed["records"]} + assert {"late-1", newest["trial_id"]} <= set(by_trial) + late_record, new_record = by_trial["late-1"], by_trial[newest["trial_id"]] + assert late_record["definition_hash"] != new_record["definition_hash"] + assert late_record["covers_current"] is False and new_record["covers_current"] is True + assert listed["summary"]["covers_current"] is True and listed["summary"]["record_id"] == new_record["id"] + # 晚到那一条照实说它不对着当前版本跑 + assert any("找不到对应的定义版本" in problem for problem in late_record["problems"]) is False + + +# ========================================================================== +# 5. 审阅:认证主体、只追加、样例匹配不是批准 +# ========================================================================== + + +async def test_a_review_binds_the_authenticated_subject_and_the_record_basis(client, documents, datasource, + monkeypatch): + """审阅的审批人只来自服务端身份:请求体写 actor 回 422,没有主体回 409;决定绑定所审记录的依据。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + draft_id = made["id"] + plant_evidence(monkeypatch, value=2, rows=1) + trial = await run_trial(client, draft_id, expect={"metrics": {"m1": 2}, "source": "fixture"}) + record = trial["validation"]["record"] + record_id = record["id"] + + forged = await client.post(f"/api/ledger/drafts/{draft_id}/validations/{record_id}/review", + json={"decision": "confirmed", "actor": "模型自己写的审批人"}, + headers={"X-Actor": "alice"}) + assert forged.status_code == 422 + + anonymous = await client.post(f"/api/ledger/drafts/{draft_id}/validations/{record_id}/review", + json={"decision": "confirmed"}) + assert anonymous.status_code == 409 and anonymous.json()["code"] == "review_actor_required" + + unknown = await client.post(f"/api/ledger/drafts/{draft_id}/validations/{record_id}/review", + json={"decision": "approved"}, headers={"X-Actor": "alice"}) + assert unknown.status_code == 422 and unknown.json()["code"] == "review_decision" + + outside = await client.post(f"/api/ledger/drafts/{draft_id}/validations/{record_id}/review", + json={"decision": "confirmed", "metrics": ["m9"]}, + headers={"X-Actor": "alice"}) + assert outside.status_code == 422 and outside.json()["code"] == "review_scope" + + made_review = await client.post(f"/api/ledger/drafts/{draft_id}/validations/{record_id}/review", + json={"decision": "confirmed", "note": "看过独立样例"}, + headers={"X-Actor": "alice"}) + assert made_review.status_code == 201, made_review.text + review = made_review.json()["record"]["review"] + assert review["decision"] == "confirmed" and review["actor"] == "alice" and review["verified"] is False + assert review["scope"] == ["m1"] and review["covers_current"] is True + assert review["basis"]["definition_hash"] == record["definition_hash"] + assert review["basis"]["method_version"] == validation.METHOD_VERSION + + listed = await validations(client, draft_id) + assert listed["summary"]["verdict"] == "verified" + assert listed["summary"]["review"]["actor"] == "alice" + + # 再审一次(另一名主体驳回):追加一条,显示用最新的一条,旧的一条还在 + again = await client.post(f"/api/ledger/drafts/{draft_id}/validations/{record_id}/review", + json={"decision": "rejected", "note": "样例覆盖不全"}, + headers={"X-Actor": "bob"}) + assert again.status_code == 201 + listed = await validations(client, draft_id) + assert listed["summary"]["verdict"] == "rejected" + assert listed["records"][0]["review"]["actor"] == "bob" + async with SessionLocal() as session: + rows = list((await session.execute(select(CaliberReviewDecision).where( + CaliberReviewDecision.record_id == record_id) + .order_by(CaliberReviewDecision.created_at.asc()))).scalars()) + assert [row.decision for row in rows] == ["confirmed", "rejected"] + assert [row.actor for row in rows] == ["alice", "bob"] + + # 记录不存在时 404;跨草稿也读不到 + missing = await client.post(f"/api/ledger/drafts/{draft_id}/validations/nope/review", + json={"decision": "confirmed"}, headers={"X-Actor": "alice"}) + assert missing.status_code == 404 + + +# ========================================================================== +# 6. 比较方法与覆盖判断本身(纯函数,R06 的原值口径) +# ========================================================================== + + +def fake_record(**over) -> CaliberValidationRecord: + """一个不落库的记录对象:只用来算覆盖、摘要和读形状。""" + fields = {"id": "rec-1", "draft_id": "d-1", "workflow_id": "wf-1", "version": 1, "card_id": "card", + "metric_ids": ["m1"], "definition_hash": "a" * 64, "binding_fingerprints": {"fetch": "b" * 64}, + "semantic_hash": "c" * 64, "execution_hash": "d" * 64, "expectation": None, + "expectation_hash": "", "expectation_source": "", "sample_id": "", "sample_version": "", + "inputs": {}, "inputs_hash": "", "method_version": validation.METHOD_VERSION, + "actual": {}, "status": validation.MATCHED, "problems": [], "trial_id": "t-1", "run_id": "r-1", + "actor": "alice", "origin": "trial"} + fields.update(over) + return CaliberValidationRecord(**fields) + + +CARD = [{"id": "m1", "name": "退款率", "contract": {"shape": "scalar"}}] + + +def actual_of_one(*, value=2, rows=1, masked=False, status="ok") -> dict: + return validation.actual_of( + metrics=[{"id": "m1", "value": None if (masked or rows == 0) else value, "status": status, + "node_id": "fetch", "masked": masked, + "quality": {"status": "pass", "checks": []}}], + queries=[{"node_id": "fetch", "total_rows": rows, "truncated": False}], + card_metrics_=CARD, metric_ids=["m1"]) + + +def test_the_method_compares_raw_values_over_the_whole_card_and_every_declared_shape(): + """方法版本 1:原值比较(不做隐式舍入)、全指标、全约定形状;没有期望只记 observed。""" + # 原值:2 与 2.0 同,字符串 "2" 与数字 2 不同(不做隐式转换) + assert validation.same_value(2, 2.0) is True + assert validation.same_value(2, "2") is False + assert validation.same_value(True, 1) is False + assert validation.same_value(2.25, 2.2500001) is False + + observed = validation.compare(expected=None, actual=actual_of_one(), metric_ids=["m1"], + card_metrics_=CARD) + assert observed["status"] == validation.OBSERVED + assert any("没有独立期望" in problem for problem in observed["problems"]) + + matched = validation.compare(expected={"m1": 2.0}, actual=actual_of_one(value=2), metric_ids=["m1"], + card_metrics_=CARD) + assert matched["status"] == validation.MATCHED and matched["actual"]["m1"]["ok"] is True + + # 期望漏了一条:全指标比较,算 mismatched 而不是「只比了几条就通过」 + partial = validation.compare(expected={"other": 1}, actual=actual_of_one(), + metric_ids=["m1", "other"], card_metrics_=CARD, problems=()) + assert partial["status"] == validation.MISMATCHED + assert any("期望没有覆盖指标" in problem for problem in partial["problems"]) + + # 卡上没有可比对的指标:不能是 matched(缺证据不得升级) + empty = validation.compare(expected={}, actual={}, metric_ids=[], card_metrics_=[]) + assert empty["status"] == validation.UNVERIFIED + + # 运行没成功:failed,且不问期望 + failed = validation.compare(expected={"m1": 2}, actual=actual_of_one(), + metric_ids=["m1"], card_metrics_=CARD, run_status="failed") + assert failed["status"] == validation.FAILED + + +def test_coverage_tracks_definition_binding_and_semantics_not_layout(): + """覆盖看得是定义/绑定/取数语义三样指纹:布局变更(版本号变了)不作废,删语义字段作废。""" + record = fake_record() + current = {"workflow_id": "wf-1", "card_id": "card", "definition_hash": "a" * 64, + "binding_fingerprints": {"fetch": "b" * 64}, "semantic_hash": "c" * 64} + assert validation.covers_current(record, current=current) is True + # 版本号(布局变更带来的)不在判断里 + assert validation.covers_current(fake_record(version=9), current=current) is True + assert validation.covers_current(record, current={**current, "definition_hash": "z" * 64}) is False + assert validation.covers_current(record, current={**current, "binding_fingerprints": {}}) is False + assert validation.covers_current(record, current={**current, "semantic_hash": "z" * 64}) is False + assert validation.covers_current(fake_record(definition_hash=""), current=current) is False + # 取数语义指纹**任一侧缺失都算不覆盖**(不得跳过这一项) + assert validation.covers_current(fake_record(semantic_hash=""), current=current) is False + assert validation.covers_current(record, current={**current, "semantic_hash": ""}) is False + + # 摘要:只有「覆盖 + matched + 认证确认**全部指标**」才是 verified;missing/stale/部分确认一律不算 + assert validation.summarize([record], current=current)["verdict"] == "unverified" + confirmed = {"decision": "confirmed", "covers_current": True, "actor": "alice", "scope": ["m1"]} + assert validation.summarize([record], current=current, + reviews={record.id: confirmed})["verdict"] == "verified" + # 空范围 / 只确认一部分:不产生卡级 verified,未确认的指标要暴露出来 + partial = validation.summarize([record], current=current, + reviews={record.id: {**confirmed, "scope": []}}) + assert partial["verdict"] == "unverified" and partial["confirmed"] == [] + assert partial["unconfirmed"] == ["m1"] and "没被确认" in partial["reason"] + assert validation.summarize([record], current=current, + reviews={record.id: {**confirmed, "scope": ["m2"]}})["verdict"] == "unverified" + assert validation.summarize([record], current={**current, "definition_hash": "z" * 64}, + reviews={record.id: {**confirmed, "covers_current": False}})["verdict"] == "stale" + assert validation.summarize([], current=current)["verdict"] == "none" + observed = validation.summarize([fake_record(status=validation.OBSERVED)], current=current) + assert observed["verdict"] == "observed" and observed["unconfirmed"] == ["m1"] + rejected = validation.summarize([record], current=current, + reviews={record.id: {"decision": "rejected", "covers_current": True, + "scope": ["m1"]}}) + assert rejected["verdict"] == "rejected" + + +def test_a_review_decision_needs_its_own_semantic_fingerprint_to_cover_current(): + """审阅决定同样按定义/绑定/取数语义三样指纹判覆盖:缺取数语义(任一侧)都算不覆盖。""" + from app.db.models import CaliberReviewDecision + + from app.ledger import review + + current = {"workflow_id": "wf-1", "card_id": "card", "definition_hash": "a" * 64, + "binding_fingerprints": {"fetch": "b" * 64}, "semantic_hash": "c" * 64} + basis = {"version": 1, "definition_hash": "a" * 64, "binding_fingerprints": {"fetch": "b" * 64}, + "semantic_hash": "c" * 64, "method_version": 1} + row = CaliberReviewDecision(id="rev-1", draft_id="d-1", record_id="rec-1", workflow_id="wf-1", + decision="confirmed", actor="alice", verified=False, scope=["m1"], + basis=dict(basis)) + assert review.covers_current(row, current=current) is True + assert review.covers_current(row, current={**current, "semantic_hash": ""}) is False + assert review.covers_current(row, current={**current, "semantic_hash": "z" * 64}) is False + missing = CaliberReviewDecision(id="rev-2", draft_id="d-1", record_id="rec-1", workflow_id="wf-1", + decision="confirmed", scope=["m1"], + basis={**basis, "semantic_hash": ""}) + assert review.covers_current(missing, current=current) is False + + +async def test_a_failed_trial_keeps_a_stable_identity_and_reading_never_grows_the_ledger( + client, documents, datasource, monkeypatch): + """反例(K05 复核):试运行没起来那一条没有身份时,每读一次就多插一行。 + + 新试运行(含起草时试运行出错这一条)必须带稳定 trial_id;老草稿里没有身份的试运行,读入口不补记。""" + async def boom(**kwargs): + raise RuntimeError("试运行没有起来") + + monkeypatch.setattr(api_ledger, "_run_trial", boom) + doc = await documents("val-stable-" + uuid.uuid4().hex[:8]) + source_id = await datasource() + fake_model(monkeypatch, plan_reply(f"{doc}-2")) + body = await extract(client, doc, source_id) + draft_id = body["draft_id"] + + detail = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + assert detail["trial"]["status"] == "failed" and detail["trial"]["trial_id"] # 稳定身份 + assert detail["trial"]["error"].startswith("试运行出错") + first = await validations(client, draft_id) + assert len(first["records"]) == 1 + [record] = first["records"] + assert record["trial_id"] == detail["trial"]["trial_id"] and record["status"] == "failed" + + # 反复读:草稿详情 / 试运行 / 验证列表各读几遍,行数不增长(以前每次生成一个随机身份 → 每次多一行) + for _ in range(3): + await client.get(f"/api/ledger/drafts/{draft_id}") + await client.get(f"/api/ledger/drafts/{draft_id}/trial") + await validations(client, draft_id) + assert len((await validations(client, draft_id))["records"]) == 1 + + +async def test_a_trial_without_a_stable_identity_is_never_appended_by_reads(client): + """反例(K05 复核):老草稿 payload 里那一条没有 trial_id / run_id 的试运行,读入口不得补记。""" + draft_id = "legacy-trial-" + uuid.uuid4().hex[:8] + stale_trial = {"version": 1, "graph_hash": "g" * 64, "execution_hash": "e" * 64, "inputs_hash": "i" * 64, + "run_id": "", "status": "needs_input", "error": "缺少必填输入:start"} + async with SessionLocal() as session: + session.add(CaliberDraft(id=draft_id, title="老草稿的试运行", status="questions_open", + payload={"metrics": [{"id": "m1", "name": "旧指标"}], "trial": stale_trial})) + await session.commit() + try: + first = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + assert first["trial"] == stale_trial + # 三个读入口各读两遍:一条都不补(没有身份就认不出「是不是同一次」) + for _ in range(2): + assert (await client.get(f"/api/ledger/drafts/{draft_id}/trial")).status_code == 200 + await validations(client, draft_id) + listed = await validations(client, draft_id) + assert listed["records"] == [] and listed["summary"]["verdict"] == "none" + # 试运行响应里这一段形状照旧,只是没有本次记录:covers_current 是 null(判不了),不是 false,也不顶别人的记录 + trial = (await client.get(f"/api/ledger/drafts/{draft_id}/trial")).json() + assert trial["validation"]["record"] is None and trial["validation"]["covers_current"] is None + assert "不能算验证通过" in trial["validation"]["note"] + finally: + async with SessionLocal() as session: + row = await session.get(CaliberDraft, draft_id) + if row is not None: + await session.delete(row) + await session.commit() + + +async def test_the_trial_validation_block_has_one_shape_and_never_borrows_another_record( + client, documents, datasource, monkeypatch): + """反例(K05 复核):GET 试运行的 validation 各分支形状不一,还会拿别的最新记录冒充本次。 + + 每个分支都给同一组键;本次没有记录时 record 是 null、covers_current 是 null,绝不退回最新一条。""" + made = await accepted_draft(client, documents, datasource, monkeypatch) + draft_id = made["id"] + keys = {"schema_version", "execution", "status", "checks", "record", "covers_current", "note"} + + ok = (await client.get(f"/api/ledger/drafts/{draft_id}/trial")).json() + assert set(ok["validation"]) == keys and ok["validation"]["record"]["trial_id"] + assert ok["validation"]["covers_current"] is True + + # 把 payload 里的试运行换成一条**没有稳定身份**的老写法(run_id 也空):本次没有记录, + # 库里明明还有别的记录,这一段也不能拿别的顶上 + async with SessionLocal() as session: + row = await session.get(CaliberDraft, draft_id) + keyless = {k: v for k, v in row.payload["trial"].items() if k != "trial_id"} + keyless.update(run_id="", status="needs_input", error="缺少必填输入:start") + row.payload = {**row.payload, "trial": keyless} + await session.commit() + before = (await validations(client, draft_id))["records"] + assert before # 库里确实有别的记录 + alone = (await client.get(f"/api/ledger/drafts/{draft_id}/trial")).json() + assert set(alone["validation"]) == keys + assert alone["validation"]["record"] is None and alone["validation"]["covers_current"] is None + assert alone["validation"]["status"] == "unknown" + assert len((await validations(client, draft_id))["records"]) == len(before) # 没有补记 + + # 换成一个这次还没记过、但有稳定身份的身份:本请求里补记一条,读回来就是它的记录 + async with SessionLocal() as session: + row = await session.get(CaliberDraft, draft_id) + row.payload = {**row.payload, "trial": {**keyless, "trial_id": "another-trial"}} + await session.commit() + after = (await client.get(f"/api/ledger/drafts/{draft_id}/trial")).json() + assert set(after["validation"]) == keys + assert after["validation"]["record"]["trial_id"] == "another-trial" + assert after["validation"]["record"]["status"] == "unverified" # 没发起运行,没有可比较的结果 + # 它对着的还是当前这张图,所以覆盖判断是 true——记录里的依据说话,不看它是哪一次 + assert after["validation"]["covers_current"] is True + + +async def test_a_partial_review_never_makes_the_whole_card_verified(client, documents, datasource, monkeypatch): + """反例(K05 复核):空范围 / 只确认一部分时不能给卡级 verified,未确认的指标要说出来。""" + doc = await documents("val-scope-" + uuid.uuid4().hex[:8]) + source = await datasource() + one = json.loads(plan_reply(f"{doc}-2")) + fake_model(monkeypatch, groups_reply(one, baseline_metrics(one))) + body = await extract(client, doc, source) + draft_id = body["draft_id"] + metrics = (await client.get(f"/api/ledger/drafts/{draft_id}")).json()["metrics"] + plant_evidence(monkeypatch, values={"m1": 2, "m2": 3}, metric_ids=[m["id"] for m in metrics], + nodes=nodes_of(metrics)) + trial = await run_trial(client, draft_id, expect={"metrics": {"m1": 2, "m2": 3}, "source": "fixture"}) + record = trial["validation"]["record"] + assert record["status"] == "matched" and record["metric_ids"] == ["m1", "m2"] + + empty = await client.post(f"/api/ledger/drafts/{draft_id}/validations/{record['id']}/review", + json={"decision": "confirmed", "metrics": []}, headers={"X-Actor": "alice"}) + assert empty.status_code == 422 and empty.json()["code"] == "review_scope" + + partial = await client.post(f"/api/ledger/drafts/{draft_id}/validations/{record['id']}/review", + json={"decision": "confirmed", "metrics": ["m1"]}, headers={"X-Actor": "alice"}) + assert partial.status_code == 201 and partial.json()["record"]["review"]["scope"] == ["m1"] + listed = await validations(client, draft_id) + assert listed["summary"]["verdict"] == "unverified" + assert listed["summary"]["confirmed"] == ["m1"] and listed["summary"]["unconfirmed"] == ["m2"] + assert "没被确认" in listed["summary"]["reason"] + + whole = await client.post(f"/api/ledger/drafts/{draft_id}/validations/{record['id']}/review", + json={"decision": "confirmed"}, headers={"X-Actor": "bob"}) + assert whole.status_code == 201 and sorted(whole.json()["record"]["review"]["scope"]) == ["m1", "m2"] + listed = await validations(client, draft_id) + assert listed["summary"]["verdict"] == "verified" and listed["summary"]["unconfirmed"] == [] + + +async def test_an_unreadable_baseline_artifact_is_never_reported_as_known(client, documents, datasource, + monkeypatch): + """反例(K05 复核):基线工件被删掉或改过时,读草稿不能报 known,也不能抛出去把页面弄崩。""" + from app.core.config import settings + + made = await accepted_draft(client, documents, datasource, monkeypatch) + baseline = made["field_baseline"] + assert baseline["status"] == "known" and baseline["readable"] is True + artifact = baseline["artifact_id"] + path = settings.data_dir / "artifacts" / artifact[:2] / f"{artifact}.json" + + original = path.read_bytes() + try: + path.write_text('{"kind": "caliber_field_baseline", "tampered": true}', encoding="utf-8") + tampered = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert tampered["field_baseline"]["status"] == "baseline_unknown" + assert tampered["field_baseline"]["readable"] is False + assert tampered["field_baseline"]["artifact_id"] == artifact + assert "读不回来" in tampered["field_baseline"]["reason"] + # 验证列表和试运行接口照常给(读页面不崩) + listed = (await client.get(f"/api/ledger/drafts/{made['id']}/validations")).json() + assert listed["field_baseline"]["status"] == "baseline_unknown" + assert (await client.get(f"/api/ledger/drafts/{made['id']}/trial")).status_code == 200 + + path.unlink() + missing = (await client.get(f"/api/ledger/drafts/{made['id']}")).json() + assert missing["field_baseline"]["status"] == "baseline_unknown" + assert missing["field_baseline"]["readable"] is False + finally: + path.write_bytes(original) + assert (await client.get(f"/api/ledger/drafts/{made['id']}")).json()["field_baseline"]["status"] == "known" + + +# ========================================================================== +# 收尾:本模块造的行(草稿由夹具清,记录/审阅跟着草稿级联,这里兜一下) +# ========================================================================== + + +@pytest.fixture(autouse=True) +async def _cleanup_records(): + yield + async with SessionLocal() as session: + drafts = list((await session.execute(select(CaliberDraft.id))).scalars()) + if drafts: + await session.execute(delete(CaliberReviewDecision).where( + CaliberReviewDecision.draft_id.in_(drafts))) + await session.execute(delete(CaliberValidationRecord).where( + CaliberValidationRecord.draft_id.in_(drafts))) + await session.commit() diff --git a/backend/tests/test_caliber_write_guard.py b/backend/tests/test_caliber_write_guard.py new file mode 100644 index 00000000..b83329e3 --- /dev/null +++ b/backend/tests/test_caliber_write_guard.py @@ -0,0 +1,477 @@ +"""K02 卡级身份、客户端版本检查与写入幂等:卡要指明、写要带基准版本、同一个 request_id 只落一次。 + +- 读草稿给出权威口径卡(card_id)和基准版本(revision); +- 已接管的草稿没带 expected_revision → 409 revision_required(老页面不能指望照旧写进去); +- 两个页面基于同一版先后保存:后一个 409 stale_revision 并带上 current_version,前一个写的内容不被盖掉(E01); +- 卡不在图上报 409 card_not_found;图上有好几张可写的卡又没指明目标报 409 card_required,指到哪张就改哪张(不取第一张); +- request_id:同键同内容重放不新增版本(基准版本过期也照旧成功——幂等在版本检查之前判),同键不同内容 409 + idempotency_conflict; +- 没碰过的配置(取数 SQL、入口字段、报告节点、图上的扩展字段)保留; +- 画布、回滚、发布单的「保存版本」走同一条 CAS:旧写 409 stale_revision,出单之后画布又改过的发布单停在保存版本那一步; +- 没接管到工作流上的老草稿照旧只改 payload,不受这几条约束。 + +模型一律注入假模型(test_ledger_docdraft_api.fake_model),试跑换成写一行 succeeded 的运行(fake_trial),不发真实请求。 +""" +from __future__ import annotations + +import copy +import json +import uuid +from types import SimpleNamespace + +import pytest +from sqlalchemy import select + +from app.core.artifact_store import graph_hash +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, Workflow, WorkflowVersion +from app.db.models_blueprints import Blueprint +from tests.test_ledger_docdraft_api import ( # noqa: F401 - client / documents / datasource / fake_trial 是 fixture + client, datasource, documents, extract, fake_model, fake_trial, plan_reply, +) + + +def cfg(graph: dict, node_id: str) -> dict: + return next(n for n in graph["nodes"] if n["id"] == node_id)["data"]["config"] + + +def _graph(label: str) -> dict: + return { + "nodes": [ + {"id": "start", "type": "input", "position": {"x": 0, "y": 0}, + "data": {"label": "输入", "config": {"fields": [{"name": "q"}]}}}, + {"id": "out", "type": "output", "position": {"x": 300, "y": 0}, + "data": {"label": label, "config": {"fields": [{"name": "r", "value": "{{ input.q }}"}]}}}, + ], + "edges": [{"source": "start", "target": "out"}], + } + + +async def _workflow(workflow_id: str) -> Workflow: + async with SessionLocal() as session: + return await session.get(Workflow, workflow_id) + + +async def _versions(workflow_id: str) -> list[int]: + async with SessionLocal() as session: + return list((await session.execute( + select(WorkflowVersion.version).where(WorkflowVersion.workflow_id == workflow_id) + .order_by(WorkflowVersion.version))).scalars()) + + +async def _graph_of(workflow_id: str, version: int | None = None) -> dict: + async with SessionLocal() as session: + workflow = await session.get(Workflow, workflow_id) + if version is None or version == workflow.version: + return copy.deepcopy(workflow.graph) + row = (await session.execute(select(WorkflowVersion).where( + WorkflowVersion.workflow_id == workflow_id, WorkflowVersion.version == version))).scalars().one() + return copy.deepcopy(row.graph) + + +async def ready_draft(client, documents, datasource, monkeypatch) -> dict: + """一份起草好、已经接管到工作流上的口径草稿(GET 的形状,带 card_id / revision)。""" + doc = await documents("guard-" + uuid.uuid4().hex) + source_id = await datasource() + fake_model(monkeypatch, plan_reply(f"{doc}-2")) + created = await extract(client, doc, source_id) + body = (await client.get(f"/api/ledger/drafts/{created['draft_id']}")).json() + assert body["status"] == "ready", body + assert body["workflow_id"], body + return body + + +#: 这个文件自己建的工作流和蓝图都叫这个名字开头:跑完删掉,不给后面的用例留下一堆它们不认识的行 +OWN_PREFIX = "K02 " + + +@pytest.fixture(autouse=True) +async def cleanup_own_rows(): + """本文件建的工作流(连同版本、幂等记录、草稿)和蓝图跑完删掉:别的用例会列它们、按计数断言。 + + 草稿本来由 documents fixture 收,这里只兜底自己的那几份(删过的再删一次是空操作)。 + """ + yield + from app.db.models import CaliberWriteRequest + + async with SessionLocal() as session: + workflow_ids = list((await session.execute( + select(Workflow.id).where(Workflow.name.like(f"{OWN_PREFIX}%")))).scalars()) + if workflow_ids: + for model in (CaliberWriteRequest, WorkflowVersion, CaliberDraft): + rows = list((await session.execute( + select(model).where(model.workflow_id.in_(workflow_ids)))).scalars()) + for row in rows: + await session.delete(row) + for workflow in list((await session.execute( + select(Workflow).where(Workflow.id.in_(workflow_ids)))).scalars()): + await session.delete(workflow) + for blueprint in list((await session.execute( + select(Blueprint).where(Blueprint.name.like(f"{OWN_PREFIX}%")))).scalars()): + await session.delete(blueprint) + await session.commit() + + +def patch_url(draft_id: str) -> str: + return f"/api/ledger/drafts/{draft_id}" + + +async def ready_draft_questions(client, documents, datasource, monkeypatch) -> dict: + """一份带两个未决问题的草稿(问题挂在指标上,消掉它要落到图上);消问题的路径用它。""" + doc = await documents("guard-q-" + uuid.uuid4().hex) + source_id = await datasource() + plan = json.loads(plan_reply(f"{doc}-2")) + plan["metrics"][0]["open_questions"] = ["按哪个时区结算", "按哪个门店口径"] + fake_model(monkeypatch, json.dumps(plan, ensure_ascii=False)) + created = await extract(client, doc, source_id) + body = (await client.get(f"/api/ledger/drafts/{created['draft_id']}")).json() + assert sorted(body["metrics"][0]["open_questions"]) == ["按哪个时区结算", "按哪个门店口径"], body + return body + + +# ========================================================================== +# 读草稿:卡和基准版本都是明确的 +# ========================================================================== + +async def test_the_draft_read_names_the_card_and_the_base_revision(client, documents, datasource, monkeypatch, + fake_trial): + body = await ready_draft(client, documents, datasource, monkeypatch) + # 起草建出来的图只有一张可写的口径卡:读的时候直接给出它的 id,客户端不用猜 + assert body["card_id"] == "card" + assert [card["id"] for card in body["cards"]] == ["card"] + # revision 就是客户端要带回来的基准版本(Workflow.version) + assert body["revision"] == body["version"] == 1 + assert (await _workflow(body["workflow_id"])).version == 1 + + +async def test_a_draft_without_a_graph_keeps_the_plain_patch_path(client, monkeypatch): + """没接管到工作流上的老草稿(连图都没有)照旧只改 payload:不要求基准版本,卡片也是空的。""" + draft_id = uuid.uuid4().hex[:32] + async with SessionLocal() as session: + session.add(CaliberDraft(id=draft_id, title="老草稿", status="ready", + payload={"metrics": [{"id": "m1", "name": "旧指标"}], "open_questions": []})) + await session.commit() + try: + res = await client.patch(patch_url(draft_id), json={"metrics": [{"id": "m1", "name": "改过的"}]}) + assert res.status_code == 200, res.text + assert res.json()["metrics"][0]["name"] == "改过的" + assert res.json()["revision"] is None and res.json()["card_id"] is None + finally: + async with SessionLocal() as session: + row = await session.get(CaliberDraft, draft_id) + if row is not None: + await session.delete(row) + await session.commit() + + +# ========================================================================== +# 客户端版本检查:已接管的资产必须带基准版本,旧写不能盖新的 +# ========================================================================== + +async def test_a_taken_over_draft_refuses_a_write_without_a_base_revision(client, documents, datasource, monkeypatch, + fake_trial): + body = await ready_draft(client, documents, datasource, monkeypatch) + metrics = copy.deepcopy(body["metrics"]) + metrics[0]["name"] = "没带基准版本" + res = await client.patch(patch_url(body["id"]), json={"metrics": metrics}) + assert res.status_code == 409, res.text + assert res.json()["code"] == "revision_required" + assert res.json()["current_version"] == 1 + # 一个版本都没多出来,图也没改 + assert await _versions(body["workflow_id"]) == [1] + assert cfg(await _graph_of(body["workflow_id"]), "card")["metrics"][0]["name"] == body["metrics"][0]["name"] + + +async def test_a_stale_page_cannot_overwrite_the_first_save(client, documents, datasource, monkeypatch, fake_trial): + """E01:两个页面基于同一版先后保存,后一个旧写被拒,不覆盖已保存的内容。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + first = copy.deepcopy(body["metrics"]) + first[0]["name"] = "先保存的" + ok = await client.patch(patch_url(body["id"]), + json={"metrics": first, "expected_revision": body["revision"]}) + assert ok.status_code == 200, ok.text + assert ok.json()["revision"] == 2 and ok.json()["metrics"][0]["name"] == "先保存的" + + # 第二个页面还拿着 v1:写不进去,服务端把当前版本交回,页面上的输入由客户端保留 + stale = copy.deepcopy(body["metrics"]) + stale[0]["name"] = "后保存的(基于旧页面)" + old = await client.patch(patch_url(body["id"]), + json={"metrics": stale, "expected_revision": body["revision"]}) + assert old.status_code == 409, old.text + assert old.json()["code"] == "stale_revision" + assert old.json()["current_version"] == 2 + assert await _versions(body["workflow_id"]) == [1, 2] + current = (await client.get(patch_url(body["id"]))).json() + assert current["metrics"][0]["name"] == "先保存的" and current["revision"] == 2 + + +async def test_the_canvas_cannot_write_a_taken_over_caliber_without_a_base_revision( + client, documents, datasource, monkeypatch, fake_trial): + """画布也是改同一份已接管资产的入口:同样要带基准版本,不能从这里绕过去。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + graph = await _graph_of(body["workflow_id"]) + cfg(graph, "card")["metrics"][0]["name"] = "画布改的" + url = f"/api/workflows/{body['workflow_id']}" + refused = await client.patch(url, json={"graph": graph}) + assert refused.status_code == 409, refused.text + assert refused.json()["code"] == "revision_required" + assert await _versions(body["workflow_id"]) == [1] + + saved = await client.patch(url, json={"graph": graph, "expected_revision": body["revision"]}) + assert saved.status_code == 200, saved.text + assert saved.json()["version"] == 2 + # 旧页面(还拿着 v1)再存一次:409 stale_revision,不覆盖 + cfg(graph, "card")["metrics"][0]["name"] = "又一个旧页面" + again = await client.patch(url, json={"graph": graph, "expected_revision": body["revision"]}) + assert again.status_code == 409 and again.json()["code"] == "stale_revision" + assert again.json()["current_version"] == 2 + + # 没接管的(手建)工作流照旧可以不带基准版本保存,老客户端不受影响 + plain = (await client.post("/api/workflows", json={"name": "K02 手建 " + uuid.uuid4().hex[:6], + "graph": _graph("a")})).json() + assert (await client.patch(f"/api/workflows/{plain['id']}", json={"graph": _graph("b")})).status_code == 200 + + +# ========================================================================== +# 卡级目标:多张卡要指明,指到哪张改哪张 +# ========================================================================== + +async def test_a_named_card_is_the_one_that_gets_written(client, documents, datasource, monkeypatch, fake_trial): + body = await ready_draft(client, documents, datasource, monkeypatch) + wid = body["workflow_id"] + # 画布上加了第二张可写的口径卡 + graph = await _graph_of(wid) + metrics = cfg(graph, "card")["metrics"] + graph["nodes"].append({"id": "card_2", "type": "metrics", "position": {"x": 0, "y": 200}, + "data": {"label": "另一张卡", "config": {"metrics": [{**metrics[0], "id": "m9", + "name": "另一张卡上的指标"}]}}}) + saved = await client.patch(f"/api/workflows/{wid}", + json={"graph": graph, "expected_revision": body["revision"]}) + assert saved.status_code == 200, saved.text + + # 读草稿仍然给出契约声明的那张卡(不是「第一张」的猜测);候选两张都列出来 + fresh = (await client.get(patch_url(body["id"]))).json() + assert fresh["card_id"] == "card" + assert [card["id"] for card in fresh["cards"]] == ["card", "card_2"] + + # 多张可写的卡、又不指明目标:拒(不做「取第一张」) + edited = copy.deepcopy(fresh["metrics"]) + edited[0]["name"] = "没指明目标" + refused = await client.patch(patch_url(body["id"]), + json={"metrics": edited, "expected_revision": fresh["revision"]}) + assert refused.status_code == 409, refused.text + assert refused.json()["code"] == "card_required" + assert [card["id"] for card in refused.json()["cards"]] == ["card", "card_2"] + + # 指到没有的卡:拒 + missing = await client.patch(patch_url(body["id"]), + json={"metrics": edited, "expected_revision": fresh["revision"], + "target": {"card_id": "card-nope"}}) + assert missing.status_code == 409 and missing.json()["code"] == "card_not_found" + + # 指到别的工作流:拒 + elsewhere = await client.patch(patch_url(body["id"]), + json={"metrics": edited, "expected_revision": fresh["revision"], + "target": {"workflow_id": "wf-elsewhere", "card_id": "card_2"}}) + assert elsewhere.status_code == 409 and elsewhere.json()["code"] == "target_mismatch" + + # 指明 card_2:改的是它,card 一个字段不动 + written = await client.patch(patch_url(body["id"]), + json={"metrics": [{"id": "m9", "name": "改在第二张卡上"}], + "expected_revision": fresh["revision"], + "target": {"workflow_id": wid, "card_id": "card_2"}}) + assert written.status_code == 200, written.text + latest = await _graph_of(wid) + assert cfg(latest, "card_2")["metrics"][0]["name"] == "改在第二张卡上" + assert cfg(latest, "card")["metrics"][0]["name"] == metrics[0]["name"] + + +# ========================================================================== +# 幂等:同一个 request_id 只落一次 +# ========================================================================== + +async def test_resolved_order_does_not_look_like_another_request(client, documents, datasource, monkeypatch, + fake_trial): + """勾选顺序变一下不该被当成另一次请求:指纹按集合归一(草稿页也把勾选去空白、去重、排序之后再发)。""" + body = await ready_draft_questions(client, documents, datasource, monkeypatch) + questions = ["按哪个时区结算", "按哪个门店口径"] + first = await client.patch(patch_url(body["id"]), + json={"resolved": questions, "expected_revision": body["revision"], + "request_id": "resolved-0001"}) + assert first.status_code == 200, first.text + assert first.json()["revision"] == 2 and first.json().get("replayed") is None + + # 同一批问题,顺序倒过来、还带一条重复的:同键同内容(重放),不是冲突、也不新增版本 + again = await client.patch(patch_url(body["id"]), + json={"resolved": [questions[1], questions[0], questions[1]], + "expected_revision": body["revision"], "request_id": "resolved-0001"}) + assert again.status_code == 200, again.text + assert again.json()["replayed"] is True + assert await _versions(body["workflow_id"]) == [1, 2] + + +async def test_the_same_request_id_replays_without_a_new_version(client, documents, datasource, monkeypatch, fake_trial): + body = await ready_draft(client, documents, datasource, monkeypatch) + metrics = copy.deepcopy(body["metrics"]) + metrics[0]["name"] = "幂等改一次" + request = {"metrics": metrics, "expected_revision": body["revision"], "request_id": "change-0001"} + + first = await client.patch(patch_url(body["id"]), json=request) + assert first.status_code == 200, first.text + assert first.json()["revision"] == 2 and first.json().get("replayed") is None + + # 同键同内容重发:基准版本这时已经过期,但幂等在版本检查之前判,照旧成功,且不再新增版本 + again = await client.patch(patch_url(body["id"]), json=request) + assert again.status_code == 200, again.text + assert again.json()["replayed"] is True and again.json()["revision"] == 2 + assert await _versions(body["workflow_id"]) == [1, 2] + + # 同键不同内容:冲突,也不新增版本 + other = await client.patch(patch_url(body["id"]), + json={**request, "metrics": [{**metrics[0], "name": "换了内容"}]}) + assert other.status_code == 409, other.text + assert other.json()["code"] == "idempotency_conflict" + assert await _versions(body["workflow_id"]) == [1, 2] + + # 换一个键、内容也有变化:照常写一版 + third = await client.patch(patch_url(body["id"]), + json={"metrics": [{**metrics[0], "name": "第二次修改"}], + "expected_revision": 2, "request_id": "change-0002"}) + assert third.status_code == 200 and third.json()["revision"] == 3 + assert await _versions(body["workflow_id"]) == [1, 2, 3] + + +# ========================================================================== +# 没碰过的配置保留 +# ========================================================================== + +async def test_untouched_config_survives_a_metrics_patch(client, documents, datasource, monkeypatch, fake_trial): + body = await ready_draft(client, documents, datasource, monkeypatch) + wid = body["workflow_id"] + before = await _graph_of(wid) + # 图上先有别人加的扩展字段(前端不认识的那些) + graph = copy.deepcopy(before) + graph["extensions"] = {"unknown": True} + cfg(graph, "fetch")["args"]["hints"] = {"keep": "me"} + saved = await client.patch(f"/api/workflows/{wid}", + json={"graph": graph, "expected_revision": body["revision"]}) + assert saved.status_code == 200, saved.text + + metrics = copy.deepcopy((await client.get(patch_url(body["id"]))).json()["metrics"]) + metrics[0]["name"] = "只改名字" + res = await client.patch(patch_url(body["id"]), + json={"metrics": metrics, "expected_revision": saved.json()["version"], + "request_id": "keep-config"}) + assert res.status_code == 200, res.text + after = await _graph_of(wid) + assert cfg(after, "fetch") == cfg(graph, "fetch") + assert cfg(after, "start") == cfg(graph, "start") + assert cfg(after, "write") == cfg(graph, "write") + assert after["extensions"] == {"unknown": True} + assert cfg(after, "card")["metrics"][0]["name"] == "只改名字" + assert cfg(after, "card")["metrics"][0]["expression"] == cfg(before, "card")["metrics"][0]["expression"] + + +# ========================================================================== +# 回滚与发布单:同一份资产、同一条 CAS +# ========================================================================== + +async def test_restore_obeys_the_same_revision_rules(client): + """回滚也是改图:已接管的资产要带基准版本,旧没带的、过期的都拒;带对了照旧回滚成新版本。""" + wid = (await client.post("/api/workflows", json={"name": "K02 回滚 " + uuid.uuid4().hex[:6], + "graph": _graph("旧图")})).json()["id"] + assert (await client.patch(f"/api/workflows/{wid}", json={"graph": _graph("新图")})).status_code == 200 + # 已经接管到工作流上(文档起草建出来的口径卡) + async with SessionLocal() as session: + workflow = await session.get(Workflow, wid) + workflow.origin = {"kind": "doc_draft"} + await session.commit() + + url = f"/api/workflows/{wid}/versions/1/restore" + missing = await client.post(url) + assert missing.status_code == 409, missing.text + assert missing.json()["code"] == "revision_required" and missing.json()["current_version"] == 2 + + stale = await client.post(url, json={"expected_revision": 1}) + assert stale.status_code == 409, stale.text + assert stale.json()["code"] == "stale_revision" and stale.json()["current_version"] == 2 + assert await _versions(wid) == [1, 2] + + ok = await client.post(url, json={"expected_revision": 2}) + assert ok.status_code == 200, ok.text + assert ok.json()["version"] == 3 and ok.json()["graph"] == _graph("旧图") + assert ok.json()["status"] == "draft" + assert await _versions(wid) == [1, 2, 3] + + +async def test_the_publish_plan_stops_when_the_canvas_moved_after_the_plan(client): + """发布单的「保存版本」和画布同一条 CAS:出单之后画布又改过,就停在这一步,不把别人刚改的图盖掉。""" + from app.blueprints.publish_plan import GRAPH_CHANGED, StepFailed, _Target, _do_save_version + + planned_graph = _graph("蓝图图") + wid = (await client.post("/api/workflows", json={"name": "K02 发布单 " + uuid.uuid4().hex[:6], + "graph": _graph("一开始的图")})).json()["id"] + async with SessionLocal() as session: + session.add(Blueprint(id=uuid.uuid4().hex[:32], name="K02 发布单", scope="shared", + spec={"template": {"id": "board", "version": 1}}, graph=planned_graph, + graph_hash=graph_hash(planned_graph), workflow_id=wid)) + await session.commit() + planned_at = (await session.get(Workflow, wid)).version # 出单时工作流是这一版 + + # 出单之后画布又存了一版:这次发布单要发的还是蓝图那张图,不能盖掉画布的修改 + saved = await client.patch(f"/api/workflows/{wid}", + json={"graph": _graph("画布改过的图"), "expected_revision": planned_at}) + assert saved.status_code == 200 and saved.json()["version"] == 2, saved.text + async with SessionLocal() as session: + workflow = await session.get(Workflow, wid) + blueprint = (await session.execute(select(Blueprint).where(Blueprint.workflow_id == wid))).scalars().one() + ctx = SimpleNamespace(bp=blueprint, options={"workflow_revision": planned_at}, + target=_Target(graph=planned_graph, digest=graph_hash(planned_graph), app_spec={}, + schedule=None, workflow=workflow, version=workflow.version + 1, + reused=False, name=workflow.name)) + with pytest.raises(StepFailed) as refused: + await _do_save_version(session, ctx) + assert refused.value.code == GRAPH_CHANGED + await session.rollback() + current = await _workflow(wid) + assert current.version == 2 and current.graph == _graph("画布改过的图") + assert await _versions(wid) == [1, 2] + + # 按现在这一版重新出单:照常存一版(蓝图那张图) + async with SessionLocal() as session: + workflow = await session.get(Workflow, wid) + blueprint = (await session.execute(select(Blueprint).where(Blueprint.workflow_id == wid))).scalars().one() + ctx = SimpleNamespace(bp=blueprint, options={"workflow_revision": workflow.version}, + target=_Target(graph=planned_graph, digest=graph_hash(planned_graph), app_spec={}, + schedule=None, workflow=workflow, version=workflow.version + 1, + reused=False, name=workflow.name)) + out = await _do_save_version(session, ctx) + assert out == {"workflow_id": wid, "version": 3, "graph_hash": graph_hash(planned_graph), "reused": False} + assert (await _workflow(wid)).graph == planned_graph + assert await _versions(wid) == [1, 2, 3] + + +async def test_the_shared_cas_refuses_a_stale_base_revision(client): + """save_graph / append_version 是同一条 CAS:基准版本过期、或者另一处先提交了新版本,都是 StaleRevision。""" + from app.apps.versions import StaleRevision, append_version, save_graph + + wid = (await client.post("/api/workflows", json={"name": "K02 CAS " + uuid.uuid4().hex[:6], + "graph": _graph("a")})).json()["id"] + async with SessionLocal() as session: + workflow = await session.get(Workflow, wid) + with pytest.raises(StaleRevision) as stale: + await save_graph(session, workflow, _graph("b"), expected_revision=workflow.version + 1) + assert stale.value.current == 1 + await session.rollback() + + async with SessionLocal() as first, SessionLocal() as second: + stale_row = await first.get(Workflow, wid) + current = await second.get(Workflow, wid) + await append_version(second, current, _graph("先到的"), note="先到的") + await second.commit() + with pytest.raises(StaleRevision) as lost: + await append_version(first, stale_row, _graph("后到的"), note="后到的") + assert lost.value.current == 2 + await first.rollback() + assert (await _workflow(wid)).graph == _graph("先到的") + assert await _versions(wid) == [1, 2] diff --git a/backend/tests/test_caliber_write_race.py b/backend/tests/test_caliber_write_race.py new file mode 100644 index 00000000..3506d4c5 --- /dev/null +++ b/backend/tests/test_caliber_write_race.py @@ -0,0 +1,176 @@ +"""K02 复核补充:已接管资产的判定、幂等的并发收敛、写入被拒之后的恢复路径。 + +- taken_over:文档起草建出来的(origin.kind=doc_draft)和 docattach 建出来的(旧产物没写 kind,按 tags 认) + 都要保护;手建、蓝图、从运行提取、固化的都不算; +- docattach 产物照样要带基准版本,旧写 409; +- 同键并发:两路都写完之前谁也看不到对方的记录,靠 CAS / 唯一键收敛——只有确认是同一件事才算重放,别的完整性 + 错误照旧抛出去,不能假成功。 +""" +from __future__ import annotations + +import copy +import uuid + +import pytest +from sqlalchemy.exc import IntegrityError + +from app.api import ledger as api_ledger +from app.apps import versions as app_versions +from app.db.base import SessionLocal +from app.db.models import CaliberWriteRequest, Workflow +from tests.test_caliber_write_guard import ( # noqa: F401 - client / documents / datasource 是 fixture + _graph_of, _versions, cfg, client, datasource, documents, extract, fake_model, fake_trial, plan_reply, + ready_draft, +) + + +# ========================================================================== +# taken_over:新旧 docattach 产物一致,不误伤别的来源 +# ========================================================================== + +def test_taken_over_covers_both_doc_draft_products_and_nothing_else(): + """判定是纯函数,按工作流的形状认:kind=doc_draft、或者 docattach 那样的 tags + origin。""" + from app.apps.versions import taken_over + + class Row: + def __init__(self, origin, tags=None): + self.origin, self.tags = origin, tags + + # 新起草:origin 里写了 kind(app/ledger/authoring.py) + assert taken_over(Row({"kind": "doc_draft", "draft_id": "d1", "documents": ["doc-1"]}, ["doc_draft"])) + # docattach(含以前建的):没有 kind,只有建的时候打的标签和那几项来源(run/sources/draft_id/documents) + assert taken_over(Row({"run_id": "run-1", "freeze": True, "sources": [{"run_id": "run-1"}], + "draft_id": "d1", "documents": ["doc-1"]}, ["doc_draft"])) + assert taken_over(Row({"run_id": "run-1"}, ["doc_draft"])) + # 别的来源都不是:手建(没有 tags/origin)、蓝图、从运行提取、固化、老数据的 None + assert not taken_over(Row(None)) + assert not taken_over(Row({})) + assert not taken_over(Row(None, [])) + assert not taken_over(Row({"blueprint_id": "bp-1", "template": "board@1"}, ["blueprint"])) + assert not taken_over(Row({"run_id": "run-1", "conversation_id": "conv-1"}, ["extracted"])) + assert not taken_over(Row({"run_id": "run-1"}, ["certified"])) + assert not taken_over(Row({"sources": [{"run_id": "run-1"}]})) + + +async def test_an_attached_caliber_cannot_be_written_without_a_base_revision(client): + """docattach 建出来的口径卡(没有 origin.kind):画布上照旧写不进去,要带基准版本。""" + wid = (await client.post("/api/workflows", json={"name": "K02 接上的 " + uuid.uuid4().hex[:6], + "graph": {"nodes": [ + {"id": "card", "type": "metrics", "position": {"x": 0, "y": 0}, + "data": {"label": "口径卡", + "config": {"metrics": [{"id": "m1", "name": "指标一", + "expression": "cell(nodes.q, 0, 'v')"}]}}}, + ], "edges": []}})).json()["id"] + async with SessionLocal() as session: + workflow = await session.get(Workflow, wid) + # 和 app/ledger/docattach.py 建出来的一模一样:tags 有 doc_draft,origin 里没有 kind + workflow.tags = ["doc_draft"] + workflow.origin = {"run_id": "run-1", "freeze": True, "sources": [{"run_id": "run-1"}], + "draft_id": "d-1", "documents": []} + await session.commit() + + url = f"/api/workflows/{wid}" + graph = {"nodes": [*copy.deepcopy((await _graph_of(wid))["nodes"])], "edges": []} + cfg(graph, "card")["metrics"][0]["name"] = "旧页面改的" + refused = await client.patch(url, json={"graph": graph}) + assert refused.status_code == 409, refused.text + assert refused.json()["code"] == "revision_required" + assert await _versions(wid) == [1] + + ok = await client.patch(url, json={"graph": graph, "expected_revision": 1}) + assert ok.status_code == 200 and ok.json()["version"] == 2, ok.text + assert await _versions(wid) == [1, 2] + + +# ========================================================================== +# 幂等的并发收敛:只有确认是同一件事才算重放 +# ========================================================================== + +async def test_a_duplicate_request_row_settles_into_a_replay(client, documents, datasource, monkeypatch, fake_trial): + """两路真并发都没查到记录时后到的那一路撞唯一键:回滚自己写的图,按赢的那一路交回重放(不报成新的一版)。 + + 注入方式:记录行事先就在,但把 claim_write 换成「一律当第一次见」——等于两路都走过了「还没写过」的判断。 + """ + body = await ready_draft(client, documents, datasource, monkeypatch) + request_id = "race-0001" + metrics = copy.deepcopy(body["metrics"]) + metrics[0]["name"] = "并发改的" + payload = api_ledger.DraftPatchIn(metrics=metrics, expected_revision=body["revision"], request_id=request_id, + target=api_ledger.DraftTargetIn(card_id=body["card_id"])) + async with SessionLocal() as session: + claim = await app_versions.claim_write(session, actor=None, workflow_id=body["workflow_id"], + target=body["card_id"], request_id=request_id, + payload_hash=api_ledger._patch_fingerprint(payload, body["card_id"])) + assert claim.state == app_versions.WRITE_NEW + + # 先埋下「赢的那一路」写过的记录(内容和这次一样) + async with SessionLocal() as session: + session.add(CaliberWriteRequest(actor="", workflow_id=body["workflow_id"], card_id=body["card_id"], + request_id=request_id, + payload_hash=api_ledger._patch_fingerprint(payload, body["card_id"]), + result={"revision": 2})) + await session.commit() + original = app_versions.claim_write + calls = {"n": 0} + + async def blind_once(*args, **kwargs): + # 只让这一次请求的「先查一遍」看不见记录(等于两路并发都没查到);回滚之后的重查走真的 + calls["n"] += 1 + if calls["n"] == 1: + return app_versions.WriteClaim(app_versions.WRITE_NEW) + return await original(*args, **kwargs) + + monkeypatch.setattr(app_versions, "claim_write", blind_once) + async with SessionLocal() as session: + out = await api_ledger.patch_draft(body["id"], payload, session=session) + monkeypatch.setattr(app_versions, "claim_write", original) + assert calls["n"] == 2, calls + assert out.get("replayed") is True, out + # 自己那一版回滚掉了:谁都没多写 + assert await _versions(body["workflow_id"]) == [1] + + +async def test_an_integrity_error_without_a_record_is_not_reported_as_success(client, documents, datasource, + monkeypatch, fake_trial): + """记请求时撞完整性错误、可记录又不在(不是同一件事):照旧抛出去,不能假成功。""" + body = await ready_draft(client, documents, datasource, monkeypatch) + metrics = copy.deepcopy(body["metrics"]) + metrics[0]["name"] = "不该成功" + payload = api_ledger.DraftPatchIn(metrics=metrics, expected_revision=body["revision"], + request_id="race-0002") + + async def boom(*args, **kwargs): + raise IntegrityError("insert", {}, Exception("UNIQUE constraint failed: workflow_versions.workflow_id")) + + monkeypatch.setattr(app_versions, "remember_write", boom) + with pytest.raises(IntegrityError): + async with SessionLocal() as session: + await api_ledger.patch_draft(body["id"], payload, session=session) + # 报错的那一次一条也没落库 + assert await _versions(body["workflow_id"]) == [1] + async with SessionLocal() as session: + rows = list((await _rows_of_write(session, body["workflow_id"]))) + assert rows == [] + assert (await client.get(f"/api/ledger/drafts/{body['id']}")).json()["revision"] == 1 + + +async def _rows_of_write(session, workflow_id: str): + from sqlalchemy import select + + return (await session.execute(select(CaliberWriteRequest.id).where( + CaliberWriteRequest.workflow_id == workflow_id))).scalars() + + +async def test_two_requests_with_the_same_key_at_once_write_once(client, documents, datasource, monkeypatch, fake_trial): + """同一个 request_id 的两路请求同时发:只落一版,两边都是 200。""" + import asyncio + + body = await ready_draft(client, documents, datasource, monkeypatch) + metrics = copy.deepcopy(body["metrics"]) + metrics[0]["name"] = "同键并发" + payload = {"metrics": metrics, "expected_revision": body["revision"], "request_id": "race-0003"} + url = f"/api/ledger/drafts/{body['id']}" + first, second = await asyncio.gather(client.patch(url, json=payload), client.patch(url, json=payload)) + assert sorted(r.status_code for r in (first, second)) == [200, 200], (first.text, second.text) + assert await _versions(body["workflow_id"]) == [1, 2] + assert [r.json().get("replayed") for r in (first, second)].count(True) <= 1 diff --git a/backend/tests/test_chat_turn_policy.py b/backend/tests/test_chat_turn_policy.py index c886f818..cf328268 100644 --- a/backend/tests/test_chat_turn_policy.py +++ b/backend/tests/test_chat_turn_policy.py @@ -45,6 +45,12 @@ def test_next_step_branches(): assert turn.next_step(_final(issues=[ERROR])) == "fail", "自查过还有 error:判失败,不再整轮重来" assert turn.next_step(_final(issues=[ERROR]), self_checked=False) == "retry", "老服务端没自查:重来一次" assert turn.next_step(_final(issues=[ERROR], autorun=False)) == "fail", "没过检查比只建不跑优先" + # 这一轮的运行已经在生成里跑完了(固定执行的 final 带 execution.run_id):运行已经发生,不能再按 ready / run 解释一遍 + done = _final(autorun=False, execution={"via": "querycore", "run_id": "run-1", "status": "succeeded"}) + assert turn.next_step(done) == "done" + assert turn.next_step(done, self_checked=False) == "done" + assert turn.next_step(_final(execution={"via": "querycore"})) == "run", "没有运行 id:不算已经跑过" + assert turn.next_step(_final(execution={"run_id": None})) == "run" assert turn.next_step({"op": "reply", "text": "已经查过了"}) == "reply" assert turn.next_step({"op": "error", "message": "x"}) == "fail" empty = {"op": "error", "message": "助手本轮未完成:模型没有给出任何修改,也没有说明原因", @@ -53,7 +59,7 @@ def test_next_step_branches(): assert turn.error_reason(empty) == "模型没有给出任何修改,也没有说明原因" assert turn.error_reason({"op": "error", "message": "助手本轮未完成:接入返回了 502"}) == "接入返回了 502" assert turn.next_step(None) == "asked", "流结束时只有反问" - assert set(turn.NEXT_STEPS) == {"run", "ready", "fail"} + assert set(turn.NEXT_STEPS) == {"run", "ready", "done", "fail"} # -------------------------------------------------------------------------- diff --git a/backend/tests/test_chat_user_caliber.py b/backend/tests/test_chat_user_caliber.py new file mode 100644 index 00000000..8938d7fc --- /dev/null +++ b/backend/tests/test_chat_user_caliber.py @@ -0,0 +1,401 @@ +"""K14 问数据集成:普通使用者一轮里看得见哪些口径、非精确问法怎么按口径取数、固定执行那一轮怎么收尾。 + +这份文件走**真实的一轮**(POST /api/conversations + POST /api/chat/turns → chat/job.ChatDriver → api/copilot.answer_ops → +look → 建图 / 固定执行 → 收尾写库),不只测 helper: + +1. **授权 look**:使用者这一轮的 system 里列着他有授权的口径(入口字段 + 按口径查询工具取数的写法),没有授权的口径一个字 + 都不出现;他这一轮也**没有** use_caliber 那段协议(把口径的取数 SQL 拷进图里那条路只给搭建者及以上); +2. **非精确问法**(「上个月<指标>是多少」):模型按查看结果搭「入口 → agent(绑 caliber_query)→ 出口」,运行真的调这个 + 工具取到数、交回的值写进答案——不是只能查底表; +3. **next 与运行归属**:命中固定执行(「<指标> 2026年9月是多少」)时 final.next = done(不是 ready),driver 把那次运行 + 收进这一轮(turn.run_id / meta.runId / run 事件)、页面据此重载查看,答案用 final 那句白话,整轮零模型、不再整轮复核; +4. **对话来源**:固定执行起的那次运行的 origin 记着这一轮的 conversation_id / turn_id,子运行记着父运行(execute_prepared)。 + +数据全是合成的(临时 SQLite 库、合成标量指标),不连真实业务库;这些指标不是任何真实业务口径。研究所用名字全是编的。 +""" +from __future__ import annotations + +import json +import uuid +from typing import Any + +import pytest +from langchain_core.messages import AIMessage, AIMessageChunk, ToolMessage +from sqlalchemy import delete, select + +from app.chat import job as chat_job +from app.chat import log as turn_log +from app.chat import turn as policy +from app.db.base import SessionLocal +from app.db.models import (CaliberDraft, Conversation, ConversationTurn, DataSource, Run, Workflow, + WorkflowPublication, WorkflowVersion) +from app.db.models_apps import App, AppGrant, AppVersion +from app.db.models_chat import ChatTurnJob +from app.engine.runner import run_manager +from app.ledger import querycore +from app.tools.datasource import MASK_RESULTS_OPTION, READ_ONLY_OPTION +from tests import eval_samples as es +from tests.fakes import auth_env +from tests.fixtures.sources import drop_source +from tests.publication_samples import make_workflow, publish +from tests.test_querycore_execute import WINDOW_SUM, fresh_source as qc_source, graph as qc_graph + +#: 口径卡的节点 id(源头口径卡) +CARD = "card" +#: 这一轮专用(全局唯一)的指标名:非精确问法和精确问法都用它,别的用例的指标名不会撞进来 +NAME = "集成口径专用净额甲" +#: 合成库的窗口:2026-09-01(含)≤ paid_at < 2026-10-01(不含) +WINDOW_INPUTS = {"start": "2026-09-01", "end": "2026-10-01"} +#: 非精确问法(remainder 拆出来是「上个月」,和指标名不等:走模型那条路) +QUESTION_FUZZY = f"上个月{NAME}是多少" +#: 精确问法(拆出来正是指标名:走固定执行那条路) +QUESTION_EXACT = f"{NAME} 2026年9月是多少" + +#: 这个文件自己建的行(跑完删掉,不给别的用例留) +_MADE: dict[str, list[str]] = {"workflows": [], "sources": [], "apps": [], "conversations": []} + + +@pytest.fixture(autouse=True) +async def engine_up(tmp_path): + await run_manager.setup() + yield + await chat_job.shutdown() + await run_manager.shutdown() + async with SessionLocal() as session: + await session.execute(delete(Run).where(Run.started_by == "uma")) + ids = list(_MADE["workflows"]) + if ids: + for model in (WorkflowPublication, WorkflowVersion, CaliberDraft): + await session.execute(delete(model).where(model.workflow_id.in_(ids))) + await session.execute(delete(Workflow).where(Workflow.id.in_(ids))) + if _MADE["apps"]: + await session.execute(delete(App).where(App.id.in_(list(_MADE["apps"])))) + if _MADE["conversations"]: + convs = list(_MADE["conversations"]) + await session.execute(delete(ChatTurnJob).where(ChatTurnJob.conversation_id.in_(convs))) + await session.execute(delete(ConversationTurn).where(ConversationTurn.conversation_id.in_(convs))) + await session.execute(delete(Conversation).where(Conversation.id.in_(convs))) + names = list(_MADE["sources"]) + await session.commit() + for name in names: + await _drop_source(name) + for key, rows in _MADE.items(): + rows.clear() + + +async def _drop_source(name: str) -> None: + async with SessionLocal() as session: + row = (await session.execute(select(DataSource).where(DataSource.name == name))).scalars().first() + if row is not None: + await drop_source(row.id) + + +def caliber_graph() -> dict[str, Any]: + """合成口径(K09 那一份)里的指标换个唯一名字:非精确问法要它不精确、精确问法要它唯一。""" + made = qc_graph() + card = next(node for node in made["nodes"] if node["id"] == CARD) + card["data"]["config"]["metrics"][0]["name"] = NAME + return made + + +async def _asset(tmp_path) -> dict: + """一份还没发布的口径资产 + 一个合成 SQLite 数据源(不连真实业务库)。""" + name = await qc_source(tmp_path) + _MADE["sources"].append(name) + asset = await make_workflow(graph=caliber_graph()) + _MADE["workflows"].append(asset["workflow_id"]) + return {**asset, "source": name} + + +async def _grant(workflow_id: str, version: int, who: str, role: str = "use") -> str: + """把这一版口径授权给这个人:未归档应用 + 当前发布版精确固定这一版 + 一条 AppGrant(资产授权就是这么来的)。""" + async with SessionLocal() as session: + row = App(name=f"集成口径授权-{uuid.uuid4().hex[:6]}", status="active", published_version=1) + session.add(row) + await session.flush() + session.add(AppVersion(app_id=row.id, version=1, spec={}, spec_hash="x", + pins=[{"alias": "cal", "workflow_id": workflow_id, "version": int(version)}])) + session.add(AppGrant(app_id=row.id, principal_kind="user", principal=who, role=role)) + await session.commit() + _MADE["apps"].append(row.id) + return row.id + + +# ========================================================================== +# 助手剧本与运行里的模型 +# ========================================================================== + + +def _line(op: dict[str, Any]) -> AIMessageChunk: + return AIMessageChunk(content=json.dumps(op, ensure_ascii=False) + "\n") + + +class CaliberCopilot: + """助手剧本:第一轮按需求 look 一次口径,第二轮按查看结果搭「入口 → agent(绑 caliber_query)→ 出口」。 + + reply_after_look 为真时第二轮直接回答(只看这一轮给了模型什么、不发起运行)。 + calls 记下每次收到的整串消息(用例据此核对:使用者的 system 里有没有口径、有没有 use_caliber 那段协议、 + 查看结果里给的是哪几个口径)。""" + + def __init__(self, source: str, *, question: str = QUESTION_FUZZY, reply_after_look: bool = False) -> None: + self.source = source + self.question = question + self.reply_after_look = reply_after_look + self.calls: list[list] = [] + + async def astream(self, messages): + self.calls.append(list(messages)) + if "上线前自查" in messages[1][1]: + yield _line({"op": "done"}) + return + if len(messages) == 2: + yield _line({"op": "plan", "summary": "先看有没有对得上的口径"}) + yield _line({"op": "look", "need": self.question, "targets": [{"kind": "caliber", "name": NAME}]}) + return + if self.reply_after_look: + yield _line({"op": "reply", "text": "这一轮只是看一眼口径。"}) + return + for op in self._graph_ops(): + yield _line(op) + + def _graph_ops(self) -> list[dict[str, Any]]: + def node(nid: str, ntype: str, label: str, **config: Any) -> dict[str, Any]: + return {"op": "add_node", "node": {"id": nid, "type": ntype, "label": label, "config": config}} + + def edge(a: str, b: str) -> dict[str, Any]: + return {"op": "add_edge", "edge": {"source": a, "target": b}} + + ask = (f"回答 {{{{ input.question }}}}:先照 system 里那些口径调 {querycore.CALIBER_QUERY} 工具取数" + "(参数照查看结果里的取数写法,inputs 按问题里的时间填,start 含、end 不含),再按交回的指标值作答") + return [node("start", "input", "输入", fields=[{"name": "question"}]), + node("ask", "agent", "按口径取数", prompt=ask, + tools=[f"db_query__{self.source}", querycore.CALIBER_QUERY], max_steps=4), + edge("start", "ask"), + node("out", "output", "答案", fields=[{"name": "答案", "value": "{{ nodes.ask.text }}"}]), + edge("ask", "out"), + {"op": "done", "explanation": "按口径取数", "run": True}] + + +def _run_model(monkeypatch, workflow_id: str, metric_ids: list[str], inputs: dict[str, Any]) -> None: + """运行里的模型:第一拍按口径调 caliber_query,拿到交回的结果后按它作答。""" + from app.providers import mock_model + + def decide(self, messages): + if any(isinstance(m, ToolMessage) for m in messages): + return AIMessage(content=f"{NAME} 是 170.00 元。") + return AIMessage(content="", tool_calls=[{ + "name": querycore.CALIBER_QUERY, "id": "call_1", + "args": {"workflow": workflow_id, "card": CARD, "metric_ids": metric_ids, "inputs": inputs}}]) + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", decide) + + +def _no_model(monkeypatch) -> None: + """任何模型调用都让这一轮炸掉:固定执行那条路应当一次模型都不调(含复核、含运行里的模型)。""" + from app.api import copilot as copilot_api + from app.providers import mock_model + + def boom(*_a, **_k): + raise AssertionError("这一轮不该调用模型") + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", boom) + monkeypatch.setattr(copilot_api, "get_chat_model", boom) + + +# ========================================================================== +# 一轮:HTTP 发起,服务端跑完(不依赖前端) +# ========================================================================== + + +async def _conversation(client, title: str = "集成:口径问数") -> str: + res = await client.post("/api/conversations", json={"kind": "chat", "title": title}) + assert res.status_code == 201, res.text + conversation_id = res.json()["id"] + _MADE["conversations"].append(conversation_id) + return conversation_id + + +async def _ask(client, conversation_id: str, question: str) -> str: + res = await client.post("/api/chat/turns", json={"conversation_id": conversation_id, "question": question}) + assert res.status_code == 202, res.text + turn_id = res.json()["turn_id"] + await chat_job.manager.wait(turn_id, timeout=90.0) + return turn_id + + +async def _row(turn_id: str) -> ConversationTurn: + async with SessionLocal() as session: + row = await session.get(ConversationTurn, turn_id) + assert row is not None + return row + + +async def _job(turn_id: str) -> ChatTurnJob: + async with SessionLocal() as session: + job = await session.get(ChatTurnJob, turn_id) + assert job is not None and job.status not in ("queued", "running"), (job.status, job.stage) + return job + + +async def _events(turn_id: str) -> list[dict[str, Any]]: + return await turn_log.read(turn_id, 0, limit=10_000) + + +def _look_text(script: Any) -> str: + """最近一次查看交回给模型的那段文字(最后一次调用的最后一条消息)。""" + return str(script.calls[-1][-1][1]) + + +def _ops(events: list[dict[str, Any]]) -> list[dict[str, Any]]: + return [event["data"] for event in events if event["type"] == "op"] + + +async def _child_runs(parent_run_id: str) -> list[Run]: + """这次运行**派生的子运行**(口径工具真跑起来的那次固定执行,K10:origin 里记着 parent_run_id)。""" + async with SessionLocal() as session: + rows = list((await session.execute(select(Run))).scalars()) + return [row for row in rows + if isinstance(row.origin, dict) and str(row.origin.get(querycore.PARENT_RUN_KEY) or "") == parent_run_id] + + +async def _unauthorized_asset(world: dict) -> dict: + """再建一份**没有**授权给 uma 的口径(同一个数据源,另一份资产):它的指标名不该出现在使用者这一轮里。""" + made = await make_workflow(graph=caliber_graph()) + _MADE["workflows"].append(made["workflow_id"]) + await publish(world["admin"], made) + return made + + +@pytest.fixture +async def world(tmp_path, monkeypatch): + """开登录的本地环境:一个普通使用者 uma + 一位管理员;合成数据源 + 一份已发布、已授权给 uma 的口径。""" + await auth_env.reset() + admin = await auth_env.turn_on_local() + await auth_env.make_user("uma", "user") + uma = await auth_env.login("uma") + assert (await admin.put("/api/auth/settings", json={"user_can_chat": True})).status_code == 200 + asset = await _asset(tmp_path) + await publish(admin, asset) + await _grant(asset["workflow_id"], 1, "uma") + try: + yield {"admin": admin, "uma": uma, "asset": asset} + finally: + await uma.aclose() + await admin.aclose() + await auth_env.reset() + + +# ========================================================================== +# 1、非精确问法:授权 look + 真实 caliber_query 工具调用 +# ========================================================================== + + +async def test_a_vague_question_uses_the_authorized_caliber_through_the_tool(world, monkeypatch): + """「上个月<指标>是多少」不精确:助手看得见**有授权的**口径与参数,按它搭 agent 调 caliber_query 取数。""" + asset = world["asset"] + # 另一份口径没授权给它:一个字都不该出现在这一轮里(清单按资产授权收窄) + hidden = await _unauthorized_asset(world) + script = CaliberCopilot(asset["source"]) + es.use_copilot(monkeypatch, script) + _run_model(monkeypatch, asset["workflow_id"], ["gmv"], WINDOW_INPUTS) + + conversation_id = await _conversation(world["uma"]) + turn_id = await _ask(world["uma"], conversation_id, QUESTION_FUZZY) + await _job(turn_id) + row = await _row(turn_id) + assert row.status == "done", row.error or row.answer + assert "170" in row.answer, row.answer + + # 授权 look:system 里列着口径这一档、写着按口径查询工具取数的写法,没有 use_caliber 那段协议 + system = str(script.calls[0][0]) + assert "口径" in system and querycore.CALIBER_QUERY in system + assert "取数写法" in system and "use_caliber" not in system, "使用者这一轮不该有拷 SQL 那条路" + # 查看结果里给的是有授权的口径:工作流 id、卡、指标 id、入口字段都在 + looked = _look_text(script) + assert asset["workflow_id"] in looked and f'"card": "{CARD}"' in looked, looked + assert '"metric_ids": [' in looked and '"gmv"' in looked and '"start"' in looked and '"end"' in looked, looked + assert hidden["workflow_id"] not in looked, "没授权的口径不该出现在查看结果里" + + # 运行真的调了这个工具:父运行是这一轮的运行,子运行按这一版口径算的数 + job = await _job(turn_id) + assert job.run_id + async with SessionLocal() as session: + run = await session.get(Run, job.run_id) + [child] = await _child_runs(run.id) + assert child.workflow_id == asset["workflow_id"] and child.version == 1 + assert run.started_by == "uma" and run.options.get(MASK_RESULTS_OPTION) is True + assert run.options.get(READ_ONLY_OPTION) is True + + +# ========================================================================== +# 2、精确问法:固定执行,next = done,运行归属这一轮 +# ========================================================================== + + +async def test_an_exact_question_settles_with_its_own_run(world, monkeypatch): + """命中固定执行:一整轮零模型,final.next = done(不是 ready),那次运行归属这一轮、页面能重载查看。""" + asset = world["asset"] + _no_model(monkeypatch) + conversation_id = await _conversation(world["uma"]) + turn_id = await _ask(world["uma"], conversation_id, QUESTION_EXACT) + + job = await _job(turn_id) + row = await _row(turn_id) + events = await _events(turn_id) + ops = _ops(events) + [final] = ops + assert final["op"] == "final", ops + execution = final["execution"] + assert execution["via"] == "querycore" and execution["status"] == "succeeded" + assert exec_metric(execution) == WINDOW_SUM + assert final["next"] == policy.NEXT_DONE, "执行已经跑完,不能再说 ready" + + # 使用者拿到的投影:没有卡 id / 工作流 id / 版本 / 清单 / 选择 / 表 / 参数 / 查询 + for key in ("card_id", "workflow_id", "version", "publication", "selection", "queries", "parameters"): + assert key not in execution, key + assert asset["workflow_id"] not in json.dumps(final, ensure_ascii=False) + + # 那次运行归属这一轮:run 事件、任务、那一行的 run_id/meta,页面据此重载查看 + [launched] = [event for event in events if event["type"] == "run"] + assert launched["data"]["run_id"] == job.run_id == row.run_id + assert row.meta["runId"] == job.run_id and row.status == "done" + assert row.answer == final["explanation"] and "170" in row.answer + assert [event["data"]["stage"] for event in events if event["type"] == "stage"] == ["build", "run"], \ + "固定执行不再整轮复核" + assert row.review == {} + + async with SessionLocal() as session: + run = await session.get(Run, job.run_id) + assert run.started_by == "uma" + assert run.options.get(MASK_RESULTS_OPTION) is True and run.options.get(READ_ONLY_OPTION) is True + # 对话来源:这次运行记着是哪段对话的哪一轮(和问数据自己发起的运行同一份) + assert run.origin["conversation_id"] == conversation_id and run.origin["turn_id"] == turn_id + [child] = await _child_runs(run.id) + assert child.workflow_id == asset["workflow_id"] and child.version == 1 + + +def exec_metric(execution: dict[str, Any]) -> Any: + """这次固定执行交回的那个数(按指标名取,使用者看到的就是它)。""" + return {m["name"]: m["value"] for m in execution["metrics"]}[NAME] + + +# ========================================================================== +# 3、搭建者及以上那一档不变:还是 use_caliber + 选用写法 +# ========================================================================== + + +async def test_a_builder_still_gets_use_caliber_and_the_compose_view(world, monkeypatch): + """搭建者及以上照旧:system 里有 use_caliber 那段协议,查看结果给的是选用写法(带版本),不是按口径查询工具那一套。""" + asset = world["asset"] + script = CaliberCopilot(asset["source"], reply_after_look=True) + es.use_copilot(monkeypatch, script) + conversation_id = await _conversation(world["admin"], title="集成:口径问数(搭建者)") + turn_id = await _ask(world["admin"], conversation_id, QUESTION_FUZZY) + row = await _row(turn_id) + assert row.status == "done", row.error + + system = str(script.calls[0][0]) + assert "选用已发布口径" in system and '"op":"use_caliber"' in system + looked = _look_text(script) + assert '"op": "use_caliber"' in looked and f'"version": {asset["version"]}' in looked, looked + assert "取数写法" not in looked and querycore.CALIBER_QUERY not in looked, "搭建者那一档不讲按口径查询工具" diff --git a/backend/tests/test_db_portable.py b/backend/tests/test_db_portable.py index 1d0e134e..86ed6a14 100644 --- a/backend/tests/test_db_portable.py +++ b/backend/tests/test_db_portable.py @@ -485,6 +485,11 @@ def test_old_postgres_databases_get_the_missing_columns_and_indexes(scratch_pg): for cid, at in (("c1", "2026-01-01"), ("c2", "2026-01-02")): conn.execute(text("INSERT INTO conversations (id, kind, archived, last_active_at) " "VALUES (:i, 'app', false, :at)"), {"i": cid, "at": at}) + # 加发布依据这一列(K07)之前建的库:这张表少「发布时要不要证明」这一列,而且它定过义:回填 false + conn.execute(text("CREATE TABLE workflow_publications (id VARCHAR PRIMARY KEY, workflow_id VARCHAR, " + "version BIGINT, level VARCHAR, manifest VARCHAR)")) + conn.execute(text("INSERT INTO workflow_publications (id, workflow_id, version, level, manifest) " + "VALUES ('p1', 'w1', 1, 'published', 'm1')")) db_base._migrate(conn) db_base._migrate(conn) runs = _columns(conn, "runs") @@ -498,6 +503,10 @@ def test_old_postgres_databases_get_the_missing_columns_and_indexes(scratch_pg): assert conn.execute(text("SELECT trigger_kind FROM schedules")).scalar_one() == "cron" indexes = {r[0] for r in conn.execute(text("SELECT indexname FROM pg_indexes WHERE tablename = 'runs'"))} assert {"ix_runs_schedule_id", "ix_runs_wf_ver_status"} <= indexes + # 补上的布尔列:类型是 boolean、缺省是 false(SQLite 的 0 换成 false),存量行回填 false 而不是 NULL + publications = _columns(conn, "workflow_publications") + assert publications["required"][0] == "boolean" and publications["required"][1].startswith("false") + assert conn.execute(text("SELECT required FROM workflow_publications WHERE id = 'p1'")).scalar_one() is False # 同一个人在同一个应用里两段没归档的助手对话:created_by 是迁移补上的列(NULL 不受约束),唯一索引照样建上 convs = {r[0] for r in conn.execute(text("SELECT indexname FROM pg_indexes WHERE tablename = 'conversations'"))} assert "ux_conversations_app_owner" in convs diff --git a/backend/tests/test_evidence_duplicate_exec.py b/backend/tests/test_evidence_duplicate_exec.py new file mode 100644 index 00000000..49a48c50 --- /dev/null +++ b/backend/tests/test_evidence_duplicate_exec.py @@ -0,0 +1,269 @@ +"""K10:同一份查询快照被执行两次(两条一模一样的取数)时的证据身份与消费。 + +同一次运行里两条完全相同的查询(循环里同一个节点跑两次、或者两个节点写了同一条 SQL)结果一样、查询 +快照的内容 id 也一样(内容寻址:同内容只存一份)。以前按 artifact 认,第二次会把第一次盖掉: + +- 封存读取(engine/evidence_reader):sealed.queries 是按 artifact 的,两条并成一条; +- 目录与 make_eid(engine/evidence):两条 query 条目的 eid 一模一样,图上、文档里分不出是哪一次; +- HTTP 证据(api/evidence):点开 [[v:Q2.r0.x]] 时出处链又把 artifact 反查成 Q1; +- 应用取快照(apps/resolve):同一节点的两次执行并成一条,exec 取第几次就不准了。 + +这份文件盯住这几条,并保证旧行为不变:**新条目**(带 query_id / execution_id / attempt)按 +(artifact, node_id, exec, execution_id) 这一类复合身份索引,同一份快照两次执行各得一个 eid、两条点得开的 +记录;**老条目**(一个执行身份字段都没有)照旧只按 artifact 算 eid、按 artifact 找,一个字都不变; +旧文档、复算、重放不变量都不受影响。 + +数据全是合成的(虚构零售库的一份地区销售额快照、真跑一次 app.analysis 的结论),落成一次封存运行后走真实的 +HTTP 证据接口与真实的复算,不连真实业务库、不读密钥。工具/模型可见的结果里不因此多出 SQL 正文或绑定值。 +""" +from __future__ import annotations + +import uuid +from types import SimpleNamespace +from typing import Any + +import pytest +from httpx import ASGITransport, AsyncClient + +from app.analysis.contract import ARTIFACT_KIND, ledger_entry +from app.apps.resolve import _query_artifact +from app.core import artifact_store +from app.core.artifact_store import canonical_json, content_hash, manifest_hash +from app.db.base import SessionLocal +from app.db.models import Run, RunEvent +from app.engine.evidence import build_catalog, compose_doc, iter_segments, make_eid, writer_catalog +from app.engine.evidence_reader import read_sealed +from app.main import app +from tests.test_analysis_evidence import SNAPSHOT, analyzed + +GRAPH = {"nodes": [{"id": "a", "type": "tool", "data": {"label": "取数"}}, + {"id": "b", "type": "tool", "data": {"label": "取数(同一条 SQL)"}}, + {"id": "an", "type": "agent", "data": {"label": "分析"}}, + {"id": "write", "type": "report", "data": {"label": "写周报"}}]} +#: 报告正文同时引两次:Q1 是第一次执行、Q2 是第二次 +TEXT = "第一次 [[v:Q1.r0.gmv]],第二次 [[v:Q2.r0.gmv]]。" +#: 这份快照进工件库后的 id(内容寻址,先算得出,好让合成的分析结论指向它) +SNAPSHOT_ID = content_hash(canonical_json(SNAPSHOT)) +#: 换个 sql 就换了一份快照(同一个节点在循环里跑两次、SQL 不重样的那种) +SNAPSHOT_B = {**SNAPSHOT, "sql": SNAPSHOT["sql"] + " LIMIT 100"} + + +@pytest.fixture +async def client(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c: + yield c + + +def step_of(node_id: str, *, exec_no: int = 1, execution_id: str | None = None, query_id: str | None = None, + attempt: int | None = None, snapshot: dict[str, Any] | None = None) -> dict[str, Any]: + """合成的一步:事件节点、第几次执行、执行身份、(可选)换一份快照内容。""" + return {"node_id": node_id, "exec": exec_no, "snapshot": snapshot or SNAPSHOT, + **{k: v for k, v in (("query_id", query_id), ("execution_id", execution_id), ("attempt", attempt)) + if v is not None}} + + +async def sealed_run(steps: list[dict[str, Any]], text: str, analysis: dict[str, Any] | None = None) -> dict[str, Any]: + """落一次封存好的运行:每一步一个 node.finished(带一条 query 台账条目),(可选)加一份分析结论, + 再按真实的写法组报告文档、按 runner 的算法封存。两步的 snapshot 一样就是「同一份快照被执行两次」。""" + run_id = uuid.uuid4().hex + events: list[tuple[int, str, str | None, dict[str, Any]]] = [(1, "run.started", None, {"input": {}})] + entries: list[dict[str, Any]] = [] + for spec in steps: + node_id = str(spec["node_id"]) + content = spec.get("snapshot") or SNAPSHOT + artifact = await artifact_store.put_json(content, kind="query_snapshot", run_id=run_id, node_id=node_id) + entry = {"kind": "query", "node_id": node_id, "exec": spec.get("exec", 1), "artifact": artifact, + "tool": "db_query__shop", "source": "shop", "columns": list(content["columns"]), + "rows": len(content["rows"]), "truncated": False, + **{k: spec[k] for k in ("query_id", "execution_id", "attempt") if k in spec}} + entries.append(entry) + events.append((len(events) + 1, "node.finished", node_id, {"evidence": [entry]})) + ledger = list(entries) + if analysis is not None: + made = await artifact_store.put_json(analysis, kind=ARTIFACT_KIND, run_id=run_id, node_id="an") + aentry = ledger_entry(analysis, node_id="an", exec_no=1, artifact=made, item="drop") + ledger.append(aentry) + events.append((len(events) + 1, "node.finished", "an", {"evidence": [aentry]})) + catalog = build_catalog(nodes={}, ledger=ledger) + doc = compose_doc(text, catalog, node_id="write", run_id=run_id) + doc_id = await artifact_store.put_json(doc, kind="report_doc", run_id=run_id, node_id="write") + events.append((len(events) + 1, "report.checked", "write", {"doc_artifact": doc_id, "ok": True})) + events.append((len(events) + 1, "run.finished", None, {"output": {}})) + async with SessionLocal() as session: + session.add(Run(id=run_id, workflow_name="重复执行", status="succeeded", run_class="exploratory", + graph=GRAPH, agent_limits={}, manifest_hash=manifest_hash(events), + manifest_seq=events[-1][0])) + await session.flush() + for seq, etype, node_id, data in events: + session.add(RunEvent(run_id=run_id, seq=seq, type=etype, node_id=node_id, ts=float(seq), data=data)) + await session.commit() + return {"run": run_id, "doc": doc, "artifact": entries[0]["artifact"], "entries": entries, "catalog": catalog} + + +def seg_id(doc: dict[str, Any], ref: str) -> str: + return next(s["id"] for s in iter_segments(doc) if s.get("ref") == ref) + + +async def chain_of(client: AsyncClient, made: dict[str, Any], ref: str) -> list[dict[str, Any]]: + seg = seg_id(made["doc"], ref) + body = (await client.get(f"/api/runs/{made['run']}/evidence/segments/{seg}")).json() + return body["chain"] + + +#: 同一个节点跑两次,两次都是同一条 SQL(内容一样、工件 id 相同) +TWO_EXECS = [step_of("a", exec_no=1, execution_id="run:a:1", query_id="wf:a", attempt=1), + step_of("a", exec_no=2, execution_id="run:a:2", query_id="wf:a", attempt=2)] + + +# ========================================================================== +# make_eid / 目录:新条目两次执行各一个 eid,老条目一字不差 +# ========================================================================== + + +def test_a_snapshot_executed_twice_gets_two_eids_on_new_entries(): + """新条目按执行身份算 eid:同一份 artifact、同一个节点跑两次也各得一个,目录里不再 Q1、Q2 同 id。""" + one = {"kind": "query", "node_id": "a", "exec": 1, "artifact": "A" * 64, "execution_id": "run:a:1", + "query_id": "wf:a", "attempt": 1} + two = {"kind": "query", "node_id": "a", "exec": 2, "artifact": "A" * 64, "execution_id": "run:a:2", + "query_id": "wf:a", "attempt": 2} + catalog = build_catalog(nodes={}, ledger=[one, two]) + assert catalog["Q1"]["eid"] != catalog["Q2"]["eid"], "同一份工件两次执行必须是两条可定位的记录" + assert catalog["Q1"]["execution_id"] == "run:a:1" and catalog["Q2"]["execution_id"] == "run:a:2" + assert catalog["Q1"]["query_id"] == catalog["Q2"]["query_id"] == "wf:a" # 逻辑身份相同 + assert catalog["Q1"]["artifact"] == catalog["Q2"]["artifact"] + + +def test_old_entries_keep_the_artifact_only_eid(): + """老条目(没有执行身份)的 eid 与以前一字不差:不把所有旧 eid 重算。""" + catalog = build_catalog(nodes={}, ledger=[{"kind": "query", "node_id": "a", "exec": 1, "artifact": "B" * 64}]) + assert catalog["Q1"]["eid"] == make_eid("query", "B" * 64, {}) + assert "execution_id" not in catalog["Q1"] + + +def test_the_model_visible_catalog_leaks_no_sql_or_binding_values(): + """工具/模型可见的那一份(写作目录)里不因此多出 SQL 正文或绑定值:新加的只有执行身份。""" + one = {"kind": "query", "node_id": "a", "exec": 1, "artifact": "C" * 64, "execution_id": "run:a:1", + "query_id": "wf:a", "attempt": 1} + two = {"kind": "query", "node_id": "a", "exec": 2, "artifact": "C" * 64, "execution_id": "run:a:2", + "query_id": "wf:a", "attempt": 2} + text = writer_catalog(build_catalog(nodes={}, ledger=[one, two]), loader=lambda _a: SNAPSHOT).text + assert "SELECT" not in text and "run:a:" not in text + assert "Q1" in text and "Q2" in text + + +# ========================================================================== +# 封存读取:两次执行逐条留着,按 exec / execution_id 取第几次 +# ========================================================================== + + +async def test_sealed_read_keeps_both_executions_and_selects_the_second(): + made = await sealed_run(TWO_EXECS, TEXT) + sealed = await read_sealed(made["run"]) + + records = sealed.query_records_of("a") + assert [r["execution_id"] for r in records] == ["run:a:1", "run:a:2"], "两次执行各留一条" + assert {r["artifact"] for r in records} == {made["artifact"]}, "内容一样、工件 id 相同" + # 按执行身份取:exec=2 取第二次,不是被盖住的那一条 + assert sealed.query_at(made["artifact"], node_id="a", exec_no=2)["execution_id"] == "run:a:2" + assert sealed.query_at(made["artifact"], node_id="a", exec_no=1)["execution_id"] == "run:a:1" + assert sealed.query_at(made["artifact"], node_id="a", execution_id="run:a:2")["execution_id"] == "run:a:2" + # 兼容:按 artifact 的那份映射照旧(老消费方按它认「这次运行交回过这件快照」) + assert sealed.queries[made["artifact"]]["node_id"] == "a" + assert set(sealed.queries) == {made["artifact"]} + + +# ========================================================================== +# HTTP 证据:图上是两条、点开认得出是哪一次 +# ========================================================================== + + +async def test_http_evidence_keeps_two_locatable_records(client): + made = await sealed_run(TWO_EXECS, TEXT) + body = (await client.get(f"/api/runs/{made['run']}/evidence")).json() + assert body["mode"] == "cited" + queries = {e["alias"]: e for e in body["evidence"] if e["kind"] == "query"} + assert set(queries) == {"Q1", "Q2"} + assert queries["Q1"]["eid"] != queries["Q2"]["eid"] # Q eid 不再冲突 + assert queries["Q1"]["artifact"] == queries["Q2"]["artifact"] == made["artifact"] + assert all(e["sealed"] is True for e in queries.values()) + + # 点开 [[v:Q2.r0.gmv]]:出处链认的是**第二次**执行,不是被盖掉的第一次 + step = next(s for s in await chain_of(client, made, "v:Q2.r0.gmv") if s["step"] == "query") + assert step["alias"] == "Q2" and step["artifact"] == made["artifact"] + assert step["execution_id"] == "run:a:2" and step["attempt"] == 2 and step["query_id"] == "wf:a" + first = next(s for s in await chain_of(client, made, "v:Q1.r0.gmv") if s["step"] == "query") + assert first["alias"] == "Q1" and first["execution_id"] == "run:a:1" and first["attempt"] == 1 + + +async def test_old_runs_query_steps_are_unchanged(client): + """老条目(只有 exec)、老文档:查询步骤里一个执行身份字段都不加,eid 还是按 artifact 算的那个—— + 期 4 之前一字不差的承诺不因此破掉。""" + made = await sealed_run([ + step_of("a", exec_no=1), + step_of("a", exec_no=2), + ], TEXT) + step = next(s for s in await chain_of(client, made, "v:Q2.r0.gmv") if s["step"] == "query") + assert step["node_id"] == "a" and step["artifact"] == made["artifact"] + assert {"query_id", "execution_id", "attempt"} & set(step) == set() + body = (await client.get(f"/api/runs/{made['run']}/evidence")).json() + queries = {e["alias"]: e for e in body["evidence"] if e["kind"] == "query"} + assert queries["Q1"]["eid"] == queries["Q2"]["eid"] == make_eid("query", made["artifact"], {}) + # exec=2 仍然取第二次(老条目也记 exec,逐次记的那份分得开) + sealed = await read_sealed(made["run"]) + assert sealed.query_at(made["artifact"], node_id="a", exec_no=2)["exec"] == 2 + assert len(sealed.query_records_of("a")) == 2 + + +async def test_the_two_records_are_locatable_across_two_nodes(client): + """两个节点写同一条 SQL:同一份快照、两个节点,各认各的。""" + made = await sealed_run([ + step_of("a", execution_id="run:a:1", query_id="wf:a"), + step_of("b", execution_id="run:b:1", query_id="wf:b"), + ], TEXT) + sealed = await read_sealed(made["run"]) + assert [r["node_id"] for r in sealed.query_records] == ["a", "b"] + step = next(s for s in await chain_of(client, made, "v:Q2.r0.gmv") if s["step"] == "query") + assert step["alias"] == "Q2" and step["node_id"] == "b" and step["execution_id"] == "run:b:1" + first = next(s for s in await chain_of(client, made, "v:Q1.r0.gmv") if s["step"] == "query") + assert first["alias"] == "Q1" and first["node_id"] == "a" + + +# ========================================================================== +# 应用取快照:exec 指的是第几次**执行**(同一份内容重复出现也不并成一条) +# ========================================================================== + + +async def test_app_selects_the_nth_execution_not_the_nth_distinct_snapshot(): + """一个节点跑三次、快照内容是 A、B、A:按 artifact 去重只剩两条(A、B),exec=3 / exec=2 都会取错; + 按执行顺序逐条记才对得上。""" + made = await sealed_run([ + step_of("a", exec_no=1, execution_id="run:a:1", snapshot=SNAPSHOT), + step_of("a", exec_no=2, execution_id="run:a:2", snapshot=SNAPSHOT_B), + step_of("a", exec_no=3, execution_id="run:a:3", snapshot=SNAPSHOT), + ], "[[v:Q1.r0.gmv]]、[[v:Q2.r0.gmv]]、[[v:Q3.r0.gmv]]。") + sealed = await read_sealed(made["run"]) + source = SimpleNamespace(sealed=sealed) + first, second, third = (e["artifact"] for e in made["entries"]) + assert first == third != second + assert _query_artifact(source, "a", 1) == first + assert _query_artifact(source, "a", 2) == second + assert _query_artifact(source, "a", 3) == third, "第三次执行取的是第三次,不是按内容去重后的最后一条" + assert _query_artifact(source, "a") == third, "不给 exec 取最后一次" + + +# ========================================================================== +# 复算:快照被执行两次时,分析结论的输入与复算照旧认得出来 +# ========================================================================== + + +async def test_recompute_still_locates_the_input_when_the_snapshot_ran_twice(client): + """分析结论的输入快照恰好也被执行了两次:出处链照样接上查询步骤,复算用封存的原内容重算、逐字段一致。""" + result = await analyzed({"Q2": (SNAPSHOT, SNAPSHOT_ID)}) + made = await sealed_run(TWO_EXECS, "按地区拆 [[a:A1]]。[[see:A1]]", analysis=result) + assert made["artifact"] == SNAPSHOT_ID # 合成的结论指的就是这次运行的那份快照 + chain = await chain_of(client, made, "a:A1") + assert "analysis_input" in {s["step"] for s in chain} + recheck = next(s for s in chain if s["step"] == "analysis_recompute") + assert recheck["status"] == "same", f"复算应按封存的原内容算出同一份结论:{recheck}" + # 输入快照那次查询照样接出查询步骤(同一份工件,不因执行了两次而接不上) + assert any(s["step"] == "query" and s["artifact"] == SNAPSHOT_ID for s in chain) diff --git a/backend/tests/test_inquiry_usage.py b/backend/tests/test_inquiry_usage.py index d3f28f8e..a46c28c6 100644 --- a/backend/tests/test_inquiry_usage.py +++ b/backend/tests/test_inquiry_usage.py @@ -235,13 +235,13 @@ async def test_post_seal_inquiries_stay_out_of_the_run_usage(monkeypatch): failed = await _until(run.id, ("failed",)) written = await append_events(run.id, [ask("这次为什么失败", A)], require="sealed") assert written and written[0].data["post_seal"] is True - assert set(failed.usage) == {"duration_ms", "wall_ms", "active_ms", "wait_ms"} + assert set(failed.usage) == {"duration_ms", "wall_ms", "active_ms", "wait_ms", "queue_ms"} state["fail"] = False await run_manager.continue_failed(run.id) row = await _until(run.id, ("succeeded",)) assert row.manifest_seq > written[0].seq, "继续运行之后重新封存,这条质询落进了新的封存范围" - assert set(row.usage) == {"duration_ms", "wall_ms", "active_ms", "wait_ms"} + assert set(row.usage) == {"duration_ms", "wall_ms", "active_ms", "wait_ms", "queue_ms"} @pytest.mark.parametrize("asked_before", [False, True], ids=["first-pause", "second-pause"]) @@ -270,10 +270,10 @@ async def test_runs_without_inquiries_keep_their_usage(): await _until(run.id, ("interrupted",)) await run_manager.resume(run.id, {"approved": True}) row = await _until(run.id, ("succeeded",)) - assert set(row.usage) == {"duration_ms", "wall_ms", "active_ms", "wait_ms"} + assert set(row.usage) == {"duration_ms", "wall_ms", "active_ms", "wait_ms", "queue_ms"} other = await run_manager.start(graph=gated(), input_payload={}) await _until(other.id, ("interrupted",)) assert await run_manager.cancel(other.id) == "cancelled" row = await _until(other.id, ("cancelled",)) - assert set(row.usage) == {"duration_ms", "wall_ms", "active_ms", "wait_ms"} + assert set(row.usage) == {"duration_ms", "wall_ms", "active_ms", "wait_ms", "queue_ms"} diff --git a/backend/tests/test_ledger_compose.py b/backend/tests/test_ledger_compose.py index 6d15fe23..4cde31b9 100644 --- a/backend/tests/test_ledger_compose.py +++ b/backend/tests/test_ledger_compose.py @@ -5,11 +5,15 @@ - 参数按口径入口的字段校验(未知字段、缺必填、类型、引号里的值带引号、裸写的值不是数),不合规拒收、原因交回模型; 只能选这一轮查看到的那一版、能组合的卡、卡上的指标,id 不能撞; - 问数据的查看对象多了口径:给入口字段和「能不能组合」,不给 SQL;「什么时候该看」换成问数据那一份;使用者不给; +- K08 S4:op.metrics 按**源卡顺序**归一(Composed.metrics、口径卡上记的 metrics、selection_hash 与执行数组都按那一份, + 调用方传的顺序与重复项都不影响);选用选项按**每个指标**判能不能组合(B 独有那条查询坏了只让 B 不可选,A 照旧给组合 + 写法),真正的实例化仍按同一条选择逐项硬校验; - 走一遍问数据的生成(剧本模型)再真跑出来:比对器把这些数标成 composed「助手选用」,整题 how=composed。 数据是虚构店铺库。 """ from __future__ import annotations +import hashlib import json import pytest @@ -22,7 +26,7 @@ from app.engine.runner import run_manager from app.engine.schema import GraphSpec, validate_graph from app.ledger import compose from app.ledger import match as ledger_match -from app.ledger import store +from app.ledger import params, store from app.look.calibers import CaliberKind from app.main import app from tests import ledger_samples as S @@ -69,12 +73,27 @@ async def test_instantiation_is_deterministic_and_copies_the_pinned_fetch(): assert fetch["data"]["config"]["tool"] == S.tool() assert fetch["data"]["config"]["args"]["sql"] == S.TEMPLATE.replace("{{ input.start }}", "2026-09-01").replace( "{{ input.end }}", "2026-09-08") + # 值渲染进去的那一次已经发生过:节点上记一份参数契约(ledger/params 的 marker),运行时的模板渲染不再碰 args—— + # 不然值里的 {{ }} 会被再解释一遍(K01 的二次渲染反例) + marker = fetch["data"]["config"]["parameters"] + assert marker["mode"] == params.LITERAL_ARGS and marker["adapter"] == params.ADAPTER == "inline_text" + # 源模板正文不写在节点上(engine/variables 会扫节点配置里的 {{ }},把占位符报成没人产出):记哈希 + 出处 + assert "template" not in marker + assert marker["template_hash"] == hashlib.sha256(S.TEMPLATE.encode("utf-8")).hexdigest() + # 契约与它注解的 args 绑定:哈希对得上才算(节点被复制、args 改过就作废,运行时回退正常渲染) + assert marker["rendered_hash"] == params.rendered_hash(fetch["data"]["config"]["args"]) + assert params.literal_keys(fetch["data"]["config"], "tool") == ("args",) + assert marker["parameters"] == [{"name": "start", "kind": "text", "declared": "string", "slot": "quoted"}, + {"name": "end", "kind": "text", "declared": "string", "slot": "quoted"}] + assert [d["name"] for d in marker["declared"]] == ["start", "end", "store"] + assert marker["source"]["workflow_id"] == wf and marker["source"]["node_id"] == "fetch" assert card["id"] == "c1" and card["type"] == "metrics" and card["data"]["label"] == "card" + # 这张卡这次算哪个指标也记在 口径卡来源 上(K08 S2:metrics 是这次的选择;整卡时这一项不写) assert card["data"]["config"]["caliber_from"] == {"workflow_id": wf, "workflow_version": 1, "node_id": "card", - "nodes": {"fetch": "c1_fetch"}} + "nodes": {"fetch": "c1_fetch"}, "metrics": ["gmv"]} assert made.edges == [{"source": "c1_fetch", "target": "c1"}] - # 缺省值补上了(store 有缺省 all),不进结果 - assert made.inputs == {"start": "2026-09-01", "end": "2026-09-08", "store": "all"} + # 这次要执行的那条取数只用到 start/end:没用到的 store 不进这次的值(也不填它的缺省值) + assert made.inputs == {"start": "2026-09-01", "end": "2026-09-08"} result = made.result() assert result["status"] == "ok" and result["card_id"] == "c1" and result["fetches"] == ["c1_fetch"] assert result["level_text"] == "受管" and result["metrics"] == [{"id": "gmv", "name": "销售额"}] @@ -89,6 +108,8 @@ async def test_instantiation_is_deterministic_and_copies_the_pinned_fetch(): ({"metrics": []}, "metrics 要写"), ({"metrics": ["profit"]}, "没有指标「profit」"), ({"inputs": {"start": "2026-09-01", "end": "2026-09-08", "city": "x"}}, "入口没有字段「city」"), + # 这一版入口声明过、只是不在这次选中的指标的范围里:说法不一样(K08 复核),照样拒 + ({"inputs": {"start": "2026-09-01", "end": "2026-09-08", "store": "east"}}, "不在这次选用的范围里"), ({"inputs": {"start": "2026-09-01"}}, "请填写「end」"), ({"inputs": {"start": "2026-09-01' OR '1'='1", "end": "2026-09-08"}}, "引号里,值里不能有引号"), ({"inputs": "start=2026-09-01"}, "inputs 要写成"), @@ -110,7 +131,9 @@ async def test_bare_slots_take_numbers_only_and_ids_must_not_clash(): with pytest.raises(compose.ComposeRefused, match="只能是数"): pool.compose({**use(wf), "inputs": {"after": "1 OR 1=1"}}, taken=set()) made = pool.compose({**use(wf), "inputs": {"after": "3"}}, taken=set()) - assert made.nodes[0]["data"]["config"]["args"]["sql"].endswith("id > 3") + fetch = made.nodes[0]["data"]["config"] + assert fetch["args"]["sql"].endswith("id > 3") + assert fetch["parameters"]["parameters"] == [{"name": "after", "kind": "text", "declared": "string", "slot": "bare"}] with pytest.raises(compose.ComposeRefused, match="撞了"): pool.compose({**use(wf), "inputs": {"after": "3"}}, taken={"c1"}) @@ -123,9 +146,12 @@ async def test_a_card_that_reads_model_output_is_listed_but_not_composable(): async with SessionLocal() as session: kind = await CaliberKind.load(session, compose=True) [option] = [o for o in kind.options if o.workflow_id == wf] - assert not option.composable and "不能复用" in option.reason + # 读模型写的数:这个指标一个也不可选(原因照实给,不是「没找到」) + assert not option.composable and "输入不全是查库结果里的格" in option.reason + assert [m["metric_id"] for m in option.unavailable_metrics] == ["gmv"] + assert option.unavailable_metrics[0]["reason"] in option.reason text, _ = await kind.detail([(i, "named") for i in kind.items if i.workflow_id == wf], 4000) - assert "不能组合" in text + assert "不能组合" in text and "输入不全是查库结果里的格" in text with pytest.raises(compose.ComposeRefused, match="不能组合"): compose.Composer(list(kind.options)).compose(use(wf), taken=set()) @@ -142,7 +168,9 @@ async def test_the_answer_look_shows_fields_and_how_to_compose_but_no_sql(): plain = await CaliberKind.load(session) objects = [(i, "named") for i in kind.items if i.workflow_id == wf] text, [record] = await kind.detail(objects, 4000) - assert "入口字段:start(string,必填);end(string,必填);store(string,缺省 all)" in text + # 入口字段只列这次可选指标要用的那几个(store 没有指标用得到,不列) + assert "入口字段:start(string,必填);end(string,必填)" in text and "store" not in text + assert "能选用的指标:销售额(gmv,要 start、end)" in text and "用不了的指标" not in text assert '"op": "use_caliber"' in text and f'"workflow_id": "{wf}"' in text and '"card": "card"' in text assert "SELECT" not in text.upper() and "orders" not in text assert record["kind"] == "caliber" and record["named"] @@ -245,6 +273,10 @@ async def test_an_answer_built_with_use_caliber_is_labelled_composed(client, mon graph = final["graph"] assert {n["id"] for n in graph["nodes"]} == {"start", "c1_fetch", "c1", "write", "out"} assert not [i for i in validate_graph(GraphSpec.model_validate(graph)).issues if i.level == "error"] + # 走过应用器、写进最终图之后,参数契约还认得出它注解的就是这条 args(K01 的哈希绑定不靠内存里的对象) + fetch = next(n for n in graph["nodes"] if n["id"] == "c1_fetch")["data"]["config"] + assert params.literal_keys(fetch, "tool") == ("args",) + assert fetch["parameters"]["rendered_hash"] == params.rendered_hash(fetch["args"]) S.script(monkeypatch, "九月第一周销售额 [[m:gmv]]。") run = await run_manager.start(graph=graph, input_payload={"question": "九月第一周卖了多少"}, origin_kind="chat") @@ -269,29 +301,36 @@ async def test_an_answer_built_with_use_caliber_is_labelled_composed(client, mon assert ref.meta["calibers"] == [f"{wf}@1"] and ref.meta["counts"]["composed"] == 1 -async def test_users_do_not_get_calibers_in_the_answer_look(monkeypatch): - """使用者(开登录后的 user 角色):问数据里不看口径、不能选用(拷进来的取数 SQL 在他的图里看得到)。""" +async def test_users_get_the_authorized_calibers_but_no_use_caliber(monkeypatch): + """使用者(开登录后的 user 角色):问数据里**看得到**自己有授权的口径(K14),但没有 use_caliber 那条路。 + + 看得到的是「按资产授权收窄过的清单 + 入口字段 + 按口径查询工具取数的写法」(look/calibers 的 query 那一档),不是把口径的 + 取数 SQL 拷进自己的图(那是搭建者及以上那一档,compose)。""" import app.api.copilot as copilot from app.api.copilot import GenerateIn + from app.api import copilot_context seen: dict = {} async def spy(session, payload, sources, **kw): - seen["kinds"] = kw.get("kinds") + seen.update(kw) raise RuntimeError("到这里就够了") monkeypatch.setattr(copilot, "_look_service", spy) monkeypatch.setattr("app.api.deps.restricted", lambda: True) with pytest.raises(RuntimeError): await copilot.answer_ops(GenerateIn(instruction="x", intent="answer")).__anext__() - assert seen["kinds"] == ("table", "capability") + assert seen["kinds"] == ("table", "capability", "caliber") + assert seen["caliber"] == copilot_context.CALIBER_QUERY, "使用者这一档只给按口径查询工具取数" monkeypatch.setattr("app.api.deps.restricted", lambda: False) with pytest.raises(RuntimeError): await copilot.answer_ops(GenerateIn(instruction="x", intent="answer")).__anext__() assert seen["kinds"] == ("table", "capability", "caliber") + assert seen["caliber"] == copilot_context.CALIBER_COMPOSE, "搭建者及以上照旧能 use_caliber" with pytest.raises(RuntimeError): await copilot.answer_ops(GenerateIn(instruction="x", intent="build")).__anext__() assert seen["kinds"] == ("table", "capability") + assert seen["caliber"] == copilot_context.CALIBER_LOOK, "画布那一档根本不看口径" # -------------------------------------------------------------------------- @@ -306,6 +345,26 @@ def test_the_protocol_says_card_is_the_cards_node_id_and_id_is_the_name_you_give assert "id 是你给这次选用起的名字" in text and "workflow_id、version、card 原样照抄" in text +def test_a_user_round_refuses_use_caliber_and_points_at_the_query_tool(): + """使用者那一轮看得见口径但不能选用:use_caliber 照实拒收、自查交回模型改用口径查询工具,不静默丢掉。 + + 没有口径这一档的入口(画布、发布前修复、升级)照旧:use_caliber 是认不出的操作,不进拒收。""" + from app.api.copilot_gen import NO_COMPOSE_TEXT, GraphApplier, _refused_issues + + op = {"op": "use_caliber", "id": "c1", "workflow_id": "wf", "version": 1, "card": "card", + "metrics": ["gmv"], "inputs": {}} + user = GraphApplier({}, [], composer=None, no_compose=True) + assert user.apply(dict(op)).changed is False + [issue] = _refused_issues(user) + assert issue["level"] == "error" and NO_COMPOSE_TEXT in issue["message"] + assert "use_caliber" in issue["for_model"] and "caliber_query" in issue["for_model"] + assert user.nodes == {} and user.edges == [], "拒收的选用一个节点、一条连线都不落地" + + plain = GraphApplier({}, []) + plain.apply(dict(op)) + assert _refused_issues(plain) == [] + + async def test_writing_your_own_id_as_the_card_is_refused_with_what_to_write_instead(): wf = await S.publish() pool = await composer() @@ -322,3 +381,274 @@ async def test_writing_your_own_id_as_the_card_is_refused_with_what_to_write_ins # 校验不放宽:照着交回的原因改成节点 id 就过 made = pool.compose(use(wf, card="card"), taken={"start"}) assert made.op_id == "c1" + + +# -------------------------------------------------------------------------- +# 只算选中的指标(K08 S2):op.metrics 贯穿参数校验与拷贝 +# -------------------------------------------------------------------------- + +#: 只有 B 那条查询用的字段(region):只选 A 时它不该被要求 +FIELDS_AB = [{"name": "start", "required": True}, {"name": "end", "required": True}, + {"name": "buyer", "required": True}] +SQL_A = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") +SQL_B = SQL_A + " AND region = '{{ input.buyer }}'" + + +def two_metric_graph(*, on_missing: bool = False, a_sql: str = SQL_A, b_sql: str = SQL_B) -> dict: + """一张卡两个指标、两条各自独立的查询;buyer 只有 B 那条用(A 不需要它)。""" + card: dict = {"caliber": "双指标", "caliber_version": "v1", + "metrics": [{"id": "gmv", "name": "销售额", "expression": "cell(nodes.fetch_a, 0, 'gmv')"}, + {"id": "n", "name": "单量", "expression": "cell(nodes.fetch_b, 0, 'n')"}]} + if on_missing: + card["on_missing"] = "null" + return S.chain(S.node("start", "input", fields=FIELDS_AB), + S.node("fetch_a", "tool", tool=S.tool(), args={"sql": a_sql}), + S.node("fetch_b", "tool", tool=S.tool(), args={"sql": b_sql}), + S.node("card", "metrics", **card), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.write.text }}"}]), + S.node("write", "report", instructions="写周销售")) + + +def shared_graph() -> dict: + """两个指标读同一条取数(共享 SQL):选一个时那条 SQL 保留,还在算另一个。""" + return S.chain(S.node("start", "input", fields=FIELDS_AB[:2]), + S.node("fetch", "tool", tool=S.tool(), args={"sql": SQL_A}), + S.node("card", "metrics", caliber="共享取数", caliber_version="v1", + metrics=[{"id": "gmv", "name": "销售额", "expression": "cell(nodes.fetch, 0, 'gmv')"}, + {"id": "n", "name": "单量", "expression": "cell(nodes.fetch, 0, 'n')"}]), + S.node("out", "output")) + + +def select(wf: str, metrics: list[str], inputs: dict | None = None, *, id: str = "c1") -> dict: + return {"op": "use_caliber", "id": id, "workflow_id": wf, "version": 1, "card": "card", + "metrics": metrics, "inputs": inputs if inputs is not None else + {"start": "2026-09-01", "end": "2026-09-08"}} + + +async def test_selecting_one_metric_no_longer_asks_for_the_other_query_s_parameters(): + """op.metrics 决定这次真正要执行哪些取数:只选 A 时不再要求 B 的参数,也只拷 A 那条查询。""" + wf = await S.publish(graph=two_metric_graph()) + pool = await composer() + made = pool.compose(select(wf, ["gmv"]), taken={"start"}) + assert [n["id"] for n in made.nodes] == ["c1_fetch_a", "c1"] + card = made.nodes[-1]["data"]["config"] + assert card["caliber_from"] == {"workflow_id": wf, "workflow_version": 1, "node_id": "card", + "nodes": {"fetch_a": "c1_fetch_a"}, "metrics": ["gmv"]} + assert made.inputs == {"start": "2026-09-01", "end": "2026-09-08"} + assert made.fetch_ids == ["c1_fetch_a"] + # 整卡(两个指标)时还是要求 B 的参数:不收窄、也不静默放宽 + with pytest.raises(compose.ComposeRefused, match="buyer"): + pool.compose(select(wf, ["gmv", "n"], id="c2"), taken={"start"}) + # 结果带上这次选择的身份与排除的查询 + result = made.result() + assert result["selection"]["mode"] == "explicit" and result["selection"]["metric_ids"] == ["gmv"] + assert result["selection"]["query_ids"] == [f"{wf}:fetch_a"] + assert result["selection"]["excluded_query_ids"] == [f"{wf}:fetch_b"] + assert result["selection"]["selection_hash"] and result["selection"]["closure_hash"] + assert "shared_queries" not in result + # 拷进来的图能过画布校验(口径卡上多记的选择不影响它) + nodes = [S.node("start", "input", fields=[{"name": "x"}]), *made.nodes, + S.node("write", "report", instructions="答"), S.node("out", "output")] + issues = validate_graph(GraphSpec.model_validate(S.chain(*nodes))).issues + assert not [i for i in issues if i.level == "error"], issues + + +async def test_a_shared_query_is_kept_and_declared_as_still_computing_the_unselected_metric(): + """A 和 B 共用一条 SQL:选 A 也保留那条 SQL,并在结果里声明它还在算 B(不做投影)。""" + wf = await S.publish(graph=shared_graph()) + made = (await composer()).compose(select(wf, ["n"]), taken={"start"}) + assert [n["id"] for n in made.nodes] == ["c1_fetch", "c1"] + assert made.nodes[-1]["data"]["config"]["caliber_from"]["metrics"] == ["n"] + result = made.result() + assert result["selection"]["metric_ids"] == ["n"] and result["selection"]["excluded_query_ids"] == [] + assert result["shared_queries"] == [{"query_id": f"{wf}:fetch", "node_id": "fetch", + "computes_unselected": ["gmv"]}] + + +async def test_a_selection_whose_dependencies_do_not_resolve_is_refused_not_widened(): + """点名的指标一个取数也不依赖(解析不出闭包):拒收,不悄悄退回整卡。""" + graph = S.chain(S.node("start", "input", fields=FIELDS_AB[:2]), + S.node("fetch", "tool", tool=S.tool(), args={"sql": SQL_A}), + S.node("card", "metrics", caliber="半个常量", caliber_version="v1", + metrics=[{"id": "gmv", "name": "销售额", "expression": "cell(nodes.fetch, 0, 'gmv')"}, + {"id": "constant", "name": "常量", "expression": "1 + 1"}]), + S.node("out", "output")) + wf = await S.publish(graph=graph) + pool = await composer() + # 整卡两张指标都在:gmv 那条查询照拷(常量指标不牵连它) + ok = pool.compose(select(wf, ["gmv"]), taken={"start"}) + assert [n["id"] for n in ok.nodes] == ["c1_fetch", "c1"] + with pytest.raises(compose.ComposeRefused) as caught: + pool.compose(select(wf, ["constant"], id="c2"), taken={"start"}) + assert "no_query_dependency" in caught.value.message and "constant" in caught.value.message + + +async def test_check_inputs_takes_the_same_selection_by_itself(): + """check_inputs 也能直接按 metrics 收窄(callers 不必先裁一份):只选 A 时不要求 B 的参数。""" + from app.ledger import derive + + wf = await S.publish(graph=two_metric_graph()) + async with SessionLocal() as session: + kind = await CaliberKind.load(session, compose=True) + [option] = [o for o in kind.options if o.workflow_id == wf] + pinned = option.pinned + values = compose.check_inputs(pinned, {"start": "2026-09-01", "end": "2026-09-08"}, metric_ids=["gmv"]) + assert values == {"start": "2026-09-01", "end": "2026-09-08"} + with pytest.raises(compose.ComposeRefused, match="buyer"): + compose.check_inputs(pinned, {"start": "2026-09-01", "end": "2026-09-08"}) + # caliber_block 拿同一份选择:改名映射只列保留的那条查询,卡上记下这次算哪个指标 + block = derive.caliber_block(pinned, prefix="c1_", metrics=["gmv"]) + assert [n["id"] for n in block.nodes] == ["c1_fetch_a", "c1_card"] + assert block.nodes[-1]["data"]["config"]["caliber_from"]["metrics"] == ["gmv"] + + +# -------------------------------------------------------------------------- +# 按指标判可组合性(K08 S4):B 用不了不牵连 A;一次选用按源卡顺序 +# -------------------------------------------------------------------------- + + +async def test_a_broken_query_of_one_metric_leaves_the_other_composable(): + """B 那条查询引用了入口没声明的字段:B 用不了,A 照旧可选、能组合、能实例化;不再把整张卡提前判死。""" + wf = await S.publish(graph=two_metric_graph(b_sql=SQL_B + " AND note = '{{ input.nope }}'")) + pool = await composer() + [option] = [o for o in pool.options if o.workflow_id == wf] + assert option.composable and [m["metric_id"] for m in option.selectable_metrics] == ["gmv"] + assert [m["metric_id"] for m in option.unavailable_metrics] == ["n"] + assert "undeclared_parameter" in option.unavailable_metrics[0]["reason"] + # 不点名(整卡)那一份算不出来:原因照实给,但按指标还能用 + assert option.default_closure is None and "undeclared_parameter" in option.reason + [sel] = option.selectable_metrics + assert sel["query_ids"] == [f"{wf}:fetch_a"] and sel["required_entry_fields"] == ["start", "end"] + blob = json.dumps(sel, ensure_ascii=False) + assert "SUM(" not in blob and "orders" not in blob and "paid_at" not in blob and '"sql"' not in blob + # 能选的照旧实例化(只拷 A 那条查询);不能选的逐项硬校验拒收,不靠预筛放宽 + made = pool.compose(select(wf, ["gmv"]), taken={"start"}) + assert [n["id"] for n in made.nodes] == ["c1_fetch_a", "c1"] + with pytest.raises(compose.ComposeRefused) as caught: + pool.compose(select(wf, ["n"], id="c2"), taken={"start"}) + assert "undeclared_parameter" in caught.value.message + # 查看结果:能选的写要哪些字段,用不了的写原因;整段没有 SQL + async with SessionLocal() as session: + kind = await CaliberKind.load(session, compose=True) + text, _ = await kind.detail([(i, "named") for i in kind.items if i.workflow_id == wf], 4000) + assert "能选用的指标:销售额(gmv,要 start、end)" in text + assert "用不了的指标:单量(n):" in text and "undeclared_parameter" in text + assert "SELECT" not in text.upper() and "orders" not in text + + +async def test_a_metric_whose_binding_is_out_of_step_does_not_close_the_whole_card(): + """B 声明了业务字段(统计时间口径)但那条取数没有受控绑定:B 用不了,A 照旧可选、能实例化(K08 S4)。""" + graph = two_metric_graph() + card = next(n for n in graph["nodes"] if n["type"] == "metrics") + card["data"]["config"]["metrics"][1]["time_role"] = "payment_time" # B 声明了,可是 fetch_b 上没有绑定 + wf = await S.publish(graph=graph) + pool = await composer() + [option] = [o for o in pool.options if o.workflow_id == wf] + assert option.composable and [m["metric_id"] for m in option.selectable_metrics] == ["gmv"] + [bad] = option.unavailable_metrics + assert bad["metric_id"] == "n" and "受控绑定" in bad["reason"] + assert option.default_closure is None and "受控绑定" in option.reason + made = pool.compose(select(wf, ["gmv"]), taken={"start"}) + assert [n["id"] for n in made.nodes] == ["c1_fetch_a", "c1"] + with pytest.raises(compose.ComposeRefused) as caught: + pool.compose(select(wf, ["n"], id="c2"), taken={"start"}) + assert "binding_unresolved" in caught.value.message + + +async def test_a_card_whose_metrics_all_fail_is_not_offered_for_composition(): + """两个指标都用不了:不提供组合写法、也不实例化,原因与每个指标的原因照实给。""" + graph = two_metric_graph(a_sql=SQL_A + " AND note = '{{ input.nope }}'", + b_sql=SQL_B + " AND note = '{{ input.nope }}'") + wf = await S.publish(graph=graph) + pool = await composer() + [option] = [o for o in pool.options if o.workflow_id == wf] + assert not option.composable and option.pinned is None and option.selectable_metrics == () + assert [m["metric_id"] for m in option.unavailable_metrics] == ["gmv", "n"] + assert "undeclared_parameter" in option.reason + with pytest.raises(compose.ComposeRefused, match="不能组合"): + pool.compose(select(wf, ["gmv"]), taken={"start"}) + async with SessionLocal() as session: + kind = await CaliberKind.load(session, compose=True) + text, _ = await kind.detail([(i, "named") for i in kind.items if i.workflow_id == wf], 4000) + assert "不能组合" in text and "undeclared_parameter" in text and "SELECT" not in text.upper() + + +async def test_a_selection_is_normalized_to_the_source_card_order(): + """一次选用里的指标一律按源卡顺序:Composed.metrics、口径卡上记的 metrics、selection_hash 与执行数组都不随 + 调用方传的顺序、重复项变(K08 S4)。""" + wf = await S.publish(graph=two_metric_graph(on_missing=True)) + pool = await composer() + both = {"start": "2026-09-01", "end": "2026-09-08", "buyer": "east"} + forward = pool.compose(select(wf, ["gmv", "n"], both), taken=set()) + backward = pool.compose(select(wf, ["n", "gmv", "n"], both), taken=set()) + assert [m["id"] for m in forward.metrics] == [m["id"] for m in backward.metrics] == ["gmv", "n"] + assert forward.result()["selection"]["metric_ids"] == ["gmv", "n"] + assert forward.nodes[-1]["data"]["config"]["caliber_from"]["metrics"] == ["gmv", "n"] + assert forward.nodes == backward.nodes and forward.edges == backward.edges + assert forward.result()["selection"]["selection_hash"] == backward.result()["selection"]["selection_hash"] + assert forward.result()["selection"]["closure_hash"] == backward.result()["selection"]["closure_hash"] + + +async def test_the_offered_option_follows_the_recommended_version(): + """K07:问数据里看到的是推荐发布版(Workflow.published_version),不是机械取最高已发布版;按指标的可选性也按那一版。""" + from app.db.models import Workflow + + wf = await S.publish(graph=two_metric_graph()) # v1:两个指标都读得出来 + await S.publish(name="周销售", version=2, workflow_id=wf, + graph=two_metric_graph(b_sql=SQL_B + " AND note = '{{ input.nope }}'")) # v2:B 坏了 + async with SessionLocal() as session: + row = await session.get(Workflow, wf) + row.published_version = 1 # 重新推回 v1 + await session.commit() + kind = await CaliberKind.load(session, compose=True) + assert {i.version for i in kind.items if i.workflow_id == wf} == {1} + [option] = [o for o in kind.options if o.workflow_id == wf] + assert option.version == 1 and option.composable and option.unavailable_metrics == () + assert [m["metric_id"] for m in option.selectable_metrics] == ["gmv", "n"] + assert option.default_closure["query_ids"] == [f"{wf}:fetch_a", f"{wf}:fetch_b"] + + +# -------------------------------------------------------------------------- +# 复核:重复的指标 id、字段「不在本次选择范围」与「入口没这个字段」 +# -------------------------------------------------------------------------- + + +async def test_a_card_with_a_duplicated_metric_id_is_never_offered_for_composition(): + """同 id 指向两条不同查询的卡:look 一个指标也不提供(理由照实)、实例化也不放行(K08 复核)。""" + graph = two_metric_graph() + card = next(n for n in graph["nodes"] if n["type"] == "metrics") + card["data"]["config"]["metrics"][1]["id"] = "gmv" # 两个 gmv:一个读 fetch_a、一个读 fetch_b + wf = await S.publish(graph=graph) + pool = await composer() + [option] = [o for o in pool.options if o.workflow_id == wf] + assert not option.composable and option.pinned is None and option.selectable_metrics == () + assert [m["metric_id"] for m in option.unavailable_metrics] == ["gmv", "gmv"] + assert all("duplicate_metric_id" in m["reason"] for m in option.unavailable_metrics) + assert "duplicate_metric_id" in (option.reason or "") + with pytest.raises(compose.ComposeRefused, match="不能组合"): + pool.compose(select(wf, ["gmv"]), taken={"start"}) + async with SessionLocal() as session: + kind = await CaliberKind.load(session, compose=True) + text, _ = await kind.detail([(i, "named") for i in kind.items if i.workflow_id == wf], 4000) + assert "不能组合" in text and "duplicate_metric_id" in text and "SELECT" not in text.upper() + + +async def test_a_field_of_another_metric_is_out_of_scope_not_missing(): + """这一版入口声明过、只是不在这次选中的指标的范围里:说法是「不在这次选用的范围里」,不是「入口没有字段」; + 真的没声明过的字段照旧说「入口没有字段」(K08 复核)。两种都拒,行为不变。""" + wf = await S.publish(graph=two_metric_graph(on_missing=True)) + pool = await composer() + both_fields = {"start": "2026-09-01", "end": "2026-09-08", "buyer": "east"} + with pytest.raises(compose.ComposeRefused) as caught: + pool.compose(select(wf, ["gmv"], both_fields), taken=set()) + message = caught.value.message + assert "「buyer」这一版入口声明过,但不在这次选用的范围里" in message + assert "这次算 gmv,只要 start、end" in message and "入口没有字段" not in message + with pytest.raises(compose.ComposeRefused) as unknown: + pool.compose(select(wf, ["gmv"], {"start": "2026-09-01", "end": "2026-09-08", "买了没": "x"}, id="c2"), + taken=set()) + assert "入口没有字段「买了没」" in unknown.value.message and "不在这次选用的范围里" not in unknown.value.message + # 两张指标都选上时 buyer 就在这次的范围里:照旧收(整卡老行为不变) + made = pool.compose(select(wf, ["gmv", "n"], both_fields, id="c3"), taken=set()) + assert made.inputs == both_fields diff --git a/backend/tests/test_ledger_derive.py b/backend/tests/test_ledger_derive.py index bc6792bd..4ca7878f 100644 --- a/backend/tests/test_ledger_derive.py +++ b/backend/tests/test_ledger_derive.py @@ -15,7 +15,7 @@ import pytest from app.db.base import SessionLocal from app.db.models import Workflow, WorkflowVersion from app.engine.schema import GraphSpec, validate_graph -from app.ledger import derive +from app.ledger import bindings, closure, derive def node(nid, ntype, label=None, **config): @@ -157,3 +157,172 @@ def test_template_problem_allows_only_entry_fields(): assert derive.template_problem("q", {"args": {"sql": "SELECT 1"}, "limit": 5}) is None assert "vars.a" in derive.template_problem("q", {"args": {"sql": "{{ vars.a }}"}}) assert "input" in derive.template_problem("q", {"args": {"sql": "{{ input }}"}}) + + +# ========================================================================== +# 只算一部分指标(K08 S2):按选择裁取数、入口字段与身份 +# ========================================================================== + +#: region 只有 B 那条查询用:只选 A 时它不该进这次的范围 +FIELDS_AB = [{"name": "start", "required": True, "type": "date"}, + {"name": "end", "required": True, "type": "date"}, + {"name": "region", "required": True}] +SQL_A = ("SELECT SUM(amount) AS gmv FROM orders WHERE paid_date >= '{{ input.start }}' " + "AND paid_date < '{{ input.end }}'") +SQL_B = SQL_A + " AND region = '{{ input.region }}'" + + +def two_metric_card(b_sql: str = SQL_B) -> dict: + """一张卡两个指标、两条各自独立的查询。""" + return chain(node("start", "input", fields=FIELDS_AB), + node("fetch_a", "tool", tool="db_query__shop_x", args={"sql": SQL_A}), + node("fetch_b", "tool", tool="db_query__shop_x", args={"sql": b_sql}), + node("card", "metrics", "双指标口径卡", caliber="双指标", caliber_version="v1", + metrics=[{"id": "a", "name": "销售额", "expression": "cell(nodes.fetch_a, 0, 'gmv')"}, + {"id": "b", "name": "区域单量", "expression": "cell(nodes.fetch_b, 0, 'gmv')"}]), + node("out", "output")) + + +def shared_card() -> dict: + """两个指标读同一条取数(共享 SQL)。""" + return chain(node("start", "input", fields=FIELDS_AB[:2]), + node("fetch", "tool", tool="db_query__shop_x", args={"sql": SQL_A}), + node("card", "metrics", "共享取数口径卡", caliber="共享", caliber_version="v1", + metrics=[{"id": "a", "name": "销售额", "expression": "cell(nodes.fetch, 0, 'gmv')"}, + {"id": "b", "name": "单量", "expression": "cell(nodes.fetch, 0, 'gmv')"}]), + node("out", "output")) + + +async def test_without_a_selection_nothing_changes_and_a_whole_card_closure_comes_along(): + """没给选择:照旧整卡——取数、入口字段、探测图一字不变,另附一份整卡闭包供调用方读身份。""" + pinned = await pinned_of(two_metric_card()) + assert [n["id"] for n in pinned.fetches] == ["fetch_a", "fetch_b"] + assert [f["name"] for f in pinned.entry_fields] == ["start", "end", "region"] + assert pinned.reads == (("fetch_a", "db_query__shop_x", ("gmv",)), + ("fetch_b", "db_query__shop_x", ("gmv",))) + assert pinned.closure is not None and pinned.closure.whole_card + assert pinned.closure.mode == closure.WHOLE_CARD and pinned.closure.metric_ids == ("a", "b") + assert pinned.binding["status"] == bindings.UNBOUND # 没声明业务字段:旧资产照旧放行 + probe = derive.caliber_probe(pinned) + assert [n["id"] for n in probe.graph["nodes"]] == [derive.ENTRY_ID, "fetch_a", "fetch_b", "card", + derive.EXIT_ID] + assert probe.graph["nodes"][0]["data"]["config"]["fields"] == FIELDS_AB + assert "metrics" not in probe.graph["nodes"][-2]["data"]["config"]["caliber_from"] + + +async def test_selecting_one_metric_copies_only_its_query_and_shortens_the_entry(): + """选 A:只拷 fetch_a,入口字段收窄到这次用的那两个,探测图的入口表单跟着变;口径卡记下这次算哪个指标。""" + pinned = await pinned_of(two_metric_card()) + one = derive.select_pinned(pinned, metric_ids=["a"]) + assert [n["id"] for n in one.fetches] == ["fetch_a"] + assert one.reads == (("fetch_a", "db_query__shop_x", ("gmv",)),) + assert [f["name"] for f in one.entry_fields] == ["start", "end"] + assert one.closure.metric_ids == ("a",) and one.closure.excluded_query_ids == (f"{pinned.workflow_id}:fetch_b",) + assert one.closure.selection_hash and one.closure.closure_hash != pinned.closure.closure_hash + probe = derive.caliber_probe(one) + nodes = {n["id"]: n for n in probe.graph["nodes"]} + assert [n["id"] for n in probe.graph["nodes"]] == [derive.ENTRY_ID, "fetch_a", "card", derive.EXIT_ID] + assert nodes[derive.ENTRY_ID]["data"]["config"]["fields"] == FIELDS_AB[:2] # 入口表单同步收窄 + assert nodes["card"]["data"]["config"]["caliber_from"] == { + "workflow_id": pinned.workflow_id, "workflow_version": 1, "node_id": "card", "metrics": ["a"]} + assert validate_graph(GraphSpec.model_validate(probe.graph)).ok + # 同一份选择从 load_pinned 走一遍:拿到同一份(闭包身份也一样) + async with SessionLocal() as session: + again = await derive.load_pinned(session, pinned.workflow_id, 1, "card", metric_ids=["a"]) + assert again.fetches == one.fetches and again.entry_fields == one.entry_fields + assert again.closure.closure_hash == one.closure.closure_hash + # 显式整卡:和上面同一道门禁,闭包是整卡的(仍是同一张图,只是不写选择) + async with SessionLocal() as session: + whole = await derive.load_pinned(session, pinned.workflow_id, 1, "card", whole_card=True) + assert [n["id"] for n in whole.fetches] == ["fetch_a", "fetch_b"] and whole.closure.whole_card + + +async def test_a_broken_query_of_the_other_metric_does_not_touch_the_selected_one(): + """B 那条查询引用了入口没声明的字段:整卡照实拒;只选 A 时它根本不在这次范围里。""" + graph = two_metric_card(b_sql=SQL_B + " AND note = '{{ input.nope }}'") + with pytest.raises(derive.NotDerivable) as whole: + await pinned_of(graph) + assert whole.value.code == derive.UNDECLARED_PARAMETER and "nope" in whole.value.message + + wf_id = await publish(graph) + async with SessionLocal() as session: + one = await derive.load_pinned(session, wf_id, 1, "card", metric_ids=["a"]) + assert [n["id"] for n in one.fetches] == ["fetch_a"] and one.closure.unresolved == () + with pytest.raises(derive.NotDerivable) as bad: + await derive.load_pinned(session, wf_id, 1, "card", metric_ids=["b"]) + assert bad.value.code == derive.SELECTION + assert "undeclared_parameter" in bad.value.message and "nope" in bad.value.message + + +async def test_an_unknown_metric_is_refused_and_never_widens_to_the_whole_card(): + pinned = await pinned_of(two_metric_card()) + with pytest.raises(derive.NotDerivable) as e: + derive.select_pinned(pinned, metric_ids=["a", "没有这个"]) + assert e.value.code == derive.SELECTION and "metric_unknown" in e.value.message + with pytest.raises(derive.NotDerivable): # 空选择:不当整卡 + derive.select_pinned(pinned, metric_ids=[]) + assert derive.select_pinned(pinned).closure.whole_card # 不给选择:整卡闭包,照旧 + + +async def test_a_shared_query_is_kept_and_says_what_else_it_still_computes(): + """共享 SQL:选 a 时那条查询保留,闭包如实声明它还在算 b(不做投影)。""" + pinned = await pinned_of(shared_card()) + one = derive.select_pinned(pinned, metric_ids=["a"]) + assert [n["id"] for n in one.fetches] == ["fetch"] + assert one.closure.excluded_query_ids == () + [query] = one.closure.queries + assert query.metric_ids == ("a",) and query.computes_unselected == ("b",) + block = derive.caliber_block(one, prefix="c1_") + assert [n["id"] for n in block.nodes] == ["c1_fetch", "c1_card"] + assert block.rename == {"fetch": "c1_fetch"} + assert block.nodes[-1]["data"]["config"]["caliber_from"]["metrics"] == ["a"] + # 走参数也一样:caliber_block(pinned, metrics=[…]) 和先裁一份等价 + assert derive.caliber_block(pinned, prefix="c1_", metrics=["a"]).nodes == block.nodes + + +async def test_a_card_with_a_duplicated_metric_id_is_refused_on_every_path(): + """同一张卡上两个指标用同一个 id、各读一条查询:整卡、点名、选择裁一份都不放行(K08 复核)。 + + 严格说这也拦住了同卡上不重的那些指标——重复的 id 是卡本身的身份问题(闭包按定义解析、运行时按指标集筛、下游按位置取 + 指标各算一份),不许悄悄挑一份。""" + made = two_metric_card() + card = next(n for n in made["nodes"] if n["id"] == "card") + card["data"]["config"]["metrics"][1]["id"] = "a" # 两个 "a":一个读 fetch_a、一个读 fetch_b + wf_id = await publish(made) + async with SessionLocal() as session: + with pytest.raises(derive.NotDerivable) as whole: + await derive.load_pinned(session, wf_id, 1, "card") + assert whole.value.code == closure.DUPLICATE_METRIC_ID and "重复" in whole.value.message + with pytest.raises(derive.NotDerivable) as picked: + await derive.load_pinned(session, wf_id, 1, "card", metric_ids=["a"]) + assert picked.value.code == closure.DUPLICATE_METRIC_ID + base = await derive.read_pinned(session, wf_id, 1, "card") # 只读这一版、不判依赖:底稿读得出来 + with pytest.raises(derive.NotDerivable) as one: + derive.select_pinned(base, metric_ids=["a"]) + assert one.value.code == derive.SELECTION and "duplicate_metric_id" in one.value.message + + +async def test_read_pinned_reads_a_version_without_judging_its_dependencies(): + """read_pinned(K08 S4)只读这一版、不判依赖:B 那条查询再坏也读得出来,入口字段与图照抄、取数节点空着。 + + look 的按指标可组合性从这一份出发——B 独有那条查询坏了不该牵连 A,所以它不能走整卡门禁那一条。""" + graph = two_metric_card(b_sql=SQL_B + " AND note = '{{ input.nope }}'") + wf_id = await publish(graph) + async with SessionLocal() as session: + base = await derive.read_pinned(session, wf_id, 1, "card") + assert base.fetches == () and base.closure is None and base.binding == {} + assert [f["name"] for f in base.entry_fields] == ["start", "end", "region"] + assert base.graph and base.card["id"] == "card" and base.node_id == "card" + # reads 是整卡认得出的那一份(只看指标式,不看 SQL 好不好):两条都在 + assert [r[0] for r in base.reads] == ["fetch_a", "fetch_b"] + # 整卡门禁照旧在 load_pinned:这一版整体派生不出来 + async with SessionLocal() as session: + with pytest.raises(derive.NotDerivable) as whole: + await derive.load_pinned(session, wf_id, 1, "card") + assert whole.value.code == derive.UNDECLARED_PARAMETER + # 按选择裁照旧能裁出 A;B 点不出来(逐项硬校验) + one = derive.select_pinned(base, metric_ids=["a"]) + assert [n["id"] for n in one.fetches] == ["fetch_a"] + with pytest.raises(derive.NotDerivable) as bad: + derive.select_pinned(base, metric_ids=["b"]) + assert bad.value.code == derive.SELECTION and "undeclared_parameter" in bad.value.message diff --git a/backend/tests/test_ledger_descriptor.py b/backend/tests/test_ledger_descriptor.py index c15d65cf..02a00fa6 100644 --- a/backend/tests/test_ledger_descriptor.py +++ b/backend/tests/test_ledger_descriptor.py @@ -1,7 +1,9 @@ """口径可调用描述(app/ledger/descriptor.py、GET /api/ledger/calibers):目录页、应用表单、外部集成用的机器可读契约。 -- 只列最新「已发布且未退役」版本里的源头口径卡:入口字段成 JSON Schema、指标照配置、依赖只报数据源和表名; -- 能不能组合按 look.calibers.card_inputs(和对账、use_caliber 同一个认法); +- 只列每个工作流**推荐发布版**(Workflow.published_version,K07:默认调用读推荐版,不机械取最高已发布版)里的源头 + 口径卡:入口字段成 JSON Schema、指标照配置、依赖只报数据源和表名; +- 能不能组合按 look.calibers.metric_options 的**每个指标**那份判定(K08 S4):B 独有那条查询坏了、绑定对不上只让 B + 不可以选;另给这一版两份闭包摘要(closure 与 selectable_metrics)和 computes_unselected 的共享声明,摘要里没有 SQL; - 出具只描述版本策略:受管级别、图里没有人工节点或写外部系统的节点才自动出具,原因照写; - 转抄别处口径卡的卡不列;响应里没有 SQL、没有参数值。 数据是虚构店铺库。 @@ -155,3 +157,117 @@ async def test_metric_constraints_and_semantic_identity_reach_the_descriptor(cli [metric] = made["metrics"] assert metric["contract"] == definition and metric["grain"] == "汇总" assert metric["time_field"] == "支付时间" and made["semantic_hash"] + + +# -------------------------------------------------------------------------- +# 按指标判可组合性(K08 S4):闭包摘要、每个指标的可用性、共享声明 +# -------------------------------------------------------------------------- + +SQL_A = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") +SQL_B = SQL_A + " AND region = '{{ input.buyer }}'" + + +def two_metric_graph(a_sql: str = SQL_A, b_sql: str = SQL_B) -> dict: + """一张卡两个指标、两条各自独立的查询;buyer 只有 B 那条用。""" + return S.chain( + S.node("start", "input", fields=[{"name": "start", "required": True}, {"name": "end", "required": True}, + {"name": "buyer", "required": True}]), + S.node("fetch_a", "tool", tool=S.tool(), args={"sql": a_sql}), + S.node("fetch_b", "tool", tool=S.tool(), args={"sql": b_sql}), + S.node("card", "metrics", caliber="双指标", caliber_version="v1", + metrics=[{"id": "gmv", "name": "销售额", "expression": "cell(nodes.fetch_a, 0, 'gmv')"}, + {"id": "n", "name": "单量", "expression": "cell(nodes.fetch_b, 0, 'n')"}]), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.card.text }}"}])) + + +def shared_sql_graph() -> dict: + """两个指标读同一条取数(共享 SQL):选一个时那条还在算另一个。""" + graph = S.caliber_graph() + next(n for n in graph["nodes"] if n["type"] == "metrics")["data"]["config"]["metrics"].append( + {"id": "n", "name": "单量", "expression": "cell(nodes.fetch, 0, 'gmv')"}) + return graph + + +def leaks_sql(text: str) -> list[str]: + """描述里不该出现的 SQL 痕迹:语句/列名/参数模板/参数值。 + + 表名是**照实列出来的**(``dependencies.tables`` 的契约就是报数据源和表名),所以不含在禁列里;禁的是 SQL 正文的 + 片段与渲染模板。""" + return [n for n in ("SUM(", "paid_at", "{{", '"sql"') if n in text] + + +async def test_the_descriptor_carries_the_default_and_per_metric_closures(client): + """描述里给这一版两份闭包摘要:closure(不点名、整卡那份)与 selectable_metrics(每个指标各自的那份)。""" + wf = await S.publish(graph=two_metric_graph()) + [made] = await descriptors(client, wf) + default = made["closure"] + assert default["whole_card"] is True and default["query_ids"] == [f"{wf}:fetch_a", f"{wf}:fetch_b"] + assert default["required_entry_fields"] == ["start", "end", "buyer"] + assert default["metric_ids"] == ["gmv", "n"] and default["resolver_version"] + assert [m["metric_id"] for m in made["selectable_metrics"]] == ["gmv", "n"] + assert made["unavailable_metrics"] == [] and made["computes_unselected"] == [] + by_metric = {m["metric_id"]: m for m in made["selectable_metrics"]} + assert by_metric["gmv"]["query_ids"] == [f"{wf}:fetch_a"] + assert by_metric["gmv"]["required_entry_fields"] == ["start", "end"] + assert by_metric["gmv"]["queries"][0]["sql_hash"] and "SELECT" not in json.dumps(made) + assert made["composable"] is True and made["compose_reason"] is None + assert leaks_sql(json.dumps(made, ensure_ascii=False)) == [] + + +async def test_a_broken_metric_does_not_close_the_whole_card(client): + """B 那条查询坏了:B 进 unavailable(带原因),A 照样可选、整卡照样可组合;不点名那一份照实说算不出来。""" + wf = await S.publish(graph=two_metric_graph(b_sql=SQL_B + " AND note = '{{ input.nope }}'")) + [made] = await descriptors(client, wf) + assert made["composable"] is True + assert [m["metric_id"] for m in made["selectable_metrics"]] == ["gmv"] + [bad] = made["unavailable_metrics"] + assert bad["metric_id"] == "n" and "undeclared_parameter" in bad["reason"] + assert made["closure"] is None and "undeclared_parameter" in made["compose_reason"] + assert leaks_sql(json.dumps(made, ensure_ascii=False)) == [] + + +async def test_a_card_whose_metrics_all_fail_is_not_composable(client): + """两个指标都用不了:不能组合,原因照实给(描述里每个指标各写各的)。""" + wf = await S.publish(graph=two_metric_graph(a_sql=SQL_A + " AND note = '{{ input.nope }}'", + b_sql=SQL_B + " AND note = '{{ input.nope }}'")) + [made] = await descriptors(client, wf) + assert made["composable"] is False + assert [m["metric_id"] for m in made["unavailable_metrics"]] == ["gmv", "n"] + assert made["closure"] is None and "undeclared_parameter" in made["compose_reason"] + assert leaks_sql(json.dumps(made, ensure_ascii=False)) == [] + + +async def test_a_shared_query_is_declared_as_still_computing_the_other_metric(client): + """A 和 B 共用一条 SQL:按指标那一份摘要声明它还在算没选中的那个指标(computes_unselected,顶层也按选择给一份)。""" + wf = await S.publish(graph=shared_sql_graph()) + [made] = await descriptors(client, wf) + by_metric = {m["metric_id"]: m for m in made["selectable_metrics"]} + [query] = by_metric["gmv"]["queries"] + assert query["query_id"] == f"{wf}:fetch" and query["node_id"] == "fetch" and query["tool"] == S.tool() + assert query["metric_ids"] == ["gmv"] and query["computes_unselected"] == ["n"] + assert query["required_entry_fields"] == ["start", "end"] and query["sql_hash"] + # 顶层按「选谁、还在算谁」两组各一条(选 gmv 时还在算 n,反过来也一样) + assert made["computes_unselected"] == [ + {"query_id": f"{wf}:fetch", "node_id": "fetch", "metric_ids": ["gmv"], "computes_unselected": ["n"]}, + {"query_id": f"{wf}:fetch", "node_id": "fetch", "metric_ids": ["n"], "computes_unselected": ["gmv"]}, + ] + assert leaks_sql(json.dumps(made, ensure_ascii=False)) == [] + + +async def test_the_descriptor_follows_the_working_versions_recommendation(client): + """K07:列出的是**推荐发布版**(Workflow.published_version),不是机械取最高已发布版。""" + from app.db.base import SessionLocal + from app.db.models import Workflow + + wf = await S.publish(name="推荐版周销售") # v1 + changed = S.caliber_graph() + next(n for n in changed["nodes"] if n["type"] == "metrics")["data"]["config"]["metrics"][0]["name"] = "销售额(改)" + await S.publish(name="推荐版周销售", version=2, workflow_id=wf, graph=changed) + async with SessionLocal() as session: + row = await session.get(Workflow, wf) + row.published_version = 1 # 把推荐版推回 v1 + await session.commit() + [made] = await descriptors(client, wf) + assert made["version"] == 1 and made["metrics"][0]["name"] == "销售额" + assert made["closure"]["query_ids"] == [f"{wf}:fetch"] diff --git a/backend/tests/test_ledger_docdraft_api.py b/backend/tests/test_ledger_docdraft_api.py index 9bc5e150..bbf18137 100644 --- a/backend/tests/test_ledger_docdraft_api.py +++ b/backend/tests/test_ledger_docdraft_api.py @@ -103,7 +103,11 @@ async def client(): @pytest.fixture(autouse=True) async def fake_trial(monkeypatch): - """试跑换成写一行 succeeded 的运行:不启动引擎、不查库,接口和 payload 的形状照真的一样。""" + """试跑换成写一行 succeeded 的运行:不启动引擎、不查库,接口和 payload 的形状照真的一样。 + + 和在跑的 `_run_trial` 一样,这里只把这次试跑先在 payload 里置成 running(替换旧指针),**终态留给调用方保存** + (extract / POST 试跑都在拿到返回值之后调 _save_trial)。终态由调用方落库,试跑带没带固定期望(K05)才不会被 + 这里的提前保存吞掉。""" made: list[str] = [] async def start(*, draft_id, workflow_id, graph, values, started_by, entry_fields=(), version=1): @@ -115,10 +119,10 @@ async def fake_trial(monkeypatch): "workflow_id": workflow_id, "version": version})) await session.commit() made.append(run_id) - trial = {**api_ledger._trial_binding(version, graph, values), - "run_id": run_id, "status": "succeeded", "error": ""} - await api_ledger._save_trial(draft_id, trial, replace=True) - return trial + binding = {**api_ledger._trial_binding(version, graph, values), "trial_id": uuid.uuid4().hex} + await api_ledger._save_trial(draft_id, {**binding, "run_id": run_id, "status": "running", "error": ""}, + replace=True) + return {**binding, "run_id": run_id, "status": "succeeded", "error": ""} monkeypatch.setattr(api_ledger, "_run_trial", start) yield made @@ -243,8 +247,10 @@ async def test_extract_produces_a_ready_draft_with_a_graph_and_a_trial(client, d assert validate_graph(GraphSpec.model_validate(workflow.graph)).ok # 试跑只读接口:契约里的形状(queries 是取数节点交回的查询快照;这次是假试跑,没有快照) + # trial_id 是真试跑本来就有的一项(_run_trial 建 binding 时写),老的必填键一个不改,validation 里另并进 K05 的记录 trial = (await client.get(f"/api/ledger/drafts/{body['draft_id']}/trial")).json() - assert set(trial) == {"run_id", "status", "metrics", "queries", "error", "version", "graph_hash", "execution_hash", "inputs_hash", "validation"} + assert set(trial) == {"run_id", "status", "metrics", "queries", "error", "version", "graph_hash", + "execution_hash", "inputs_hash", "trial_id", "validation"} assert trial["run_id"] == made["trial"]["run_id"] and trial["status"] == "succeeded" assert trial["queries"] == [] @@ -344,9 +350,11 @@ async def test_patch_replaces_metrics_and_clears_resolved_questions(client, docu draft_id = (await extract(client, doc, source_id))["draft_id"] fixed = {**copy.deepcopy(json.loads(plan_reply(f"{doc}-2"))["metrics"][0]), "name": "已支付退款率(按支付日)"} + # 已接管的草稿:写要带上读到的基准版本(K02) + revision = (await client.get(f"/api/ledger/drafts/{draft_id}")).json()["revision"] res = await client.patch(f"/api/ledger/drafts/{draft_id}", json={"title": "退款率口径", "metrics": [fixed], - "resolved": ["按哪个时区结算"]}) + "resolved": ["按哪个时区结算"], "expected_revision": revision}) assert res.status_code == 200, res.text made = res.json() assert made["title"] == "退款率口径" and made["status"] == "ready" @@ -363,14 +371,16 @@ async def test_patch_replaces_metrics_and_clears_resolved_questions(client, docu assert [m["name"] for m in card["data"]["config"]["metrics"]] == ["已支付退款率(按支付日)"] # 结构不对的指标 422,草稿不动 - bad = await client.patch(f"/api/ledger/drafts/{draft_id}", json={"metrics": [{"synonyms": ["x"]}]}) + bad = await client.patch(f"/api/ledger/drafts/{draft_id}", + json={"metrics": [{"synonyms": ["x"]}], "expected_revision": made["revision"]}) assert bad.status_code == 422 still = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() assert [m["name"] for m in still["metrics"]] == ["已支付退款率(按支付日)"] # 还有问题(只换指标、带着新问题)→ questions_open res = await client.patch(f"/api/ledger/drafts/{draft_id}", - json={"metrics": [{**fixed, "open_questions": ["按哪个门店口径"]}]}) + json={"metrics": [{**fixed, "open_questions": ["按哪个门店口径"]}], + "expected_revision": made["revision"]}) assert res.json()["status"] == "questions_open" and res.json()["question_count"] == 1 @@ -381,9 +391,10 @@ async def test_draft_view_reads_the_graph_so_canvas_edits_show_up(client, docume fake_model(monkeypatch, plan_reply(f"{doc}-2")) draft_id = (await extract(client, doc, source_id))["draft_id"] - # 必须走画布的真实保存接口:它新增 v2,不能直接覆盖 v1 来模拟 + # 必须走画布的真实保存接口:它新增 v2,不能直接覆盖 v1 来模拟。已接管的资产要带基准版本(K02) async with SessionLocal() as session: draft = await session.get(CaliberDraft, draft_id) + workflow = await session.get(Workflow, draft.workflow_id) row = (await session.execute(select(WorkflowVersion).where( WorkflowVersion.workflow_id == draft.workflow_id, WorkflowVersion.version == 1))).scalars().one() @@ -393,8 +404,9 @@ async def test_draft_view_reads_the_graph_so_canvas_edits_show_up(client, docume node["data"]["config"]["metrics"][0]["name"] = "已支付退款率(画布改过)" if node["type"] == "tool" and (node["data"]["config"].get("args") or {}).get("sql"): node["data"]["config"]["args"]["sql"] = "SELECT 1 AS refund_rate" - workflow_id = draft.workflow_id - saved = await client.patch(f"/api/workflows/{workflow_id}", json={"graph": graph}) + workflow_id, revision = draft.workflow_id, workflow.version + saved = await client.patch(f"/api/workflows/{workflow_id}", + json={"graph": graph, "expected_revision": revision}) assert saved.status_code == 200 and saved.json()["version"] == 2, saved.text made = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() @@ -417,7 +429,8 @@ async def test_resolving_a_metric_question_writes_it_back_to_the_graph(client, d assert made["status"] == "questions_open" assert made["metrics"][0]["open_questions"] == ["按哪个门店口径"] - res = await client.patch(f"/api/ledger/drafts/{draft_id}", json={"resolved": ["按哪个门店口径"]}) + res = await client.patch(f"/api/ledger/drafts/{draft_id}", + json={"resolved": ["按哪个门店口径"], "expected_revision": made["revision"]}) assert res.status_code == 200, res.text fixed = res.json() assert fixed["status"] == "ready" and fixed["question_count"] == 0 @@ -442,6 +455,7 @@ async def test_trial_validates_against_graph_entry_fields_after_canvas_edit( async with SessionLocal() as session: draft = await session.get(CaliberDraft, draft_id) + workflow = await session.get(Workflow, draft.workflow_id) row = (await session.execute(select(WorkflowVersion).where( WorkflowVersion.workflow_id == draft.workflow_id, WorkflowVersion.version == 1))).scalars().one() @@ -451,8 +465,9 @@ async def test_trial_validates_against_graph_entry_fields_after_canvas_edit( node["data"]["config"]["fields"].append( {"name": "region", "type": "string", "required": True, "default": "", "description": "区域"}) - workflow_id = draft.workflow_id - saved = await client.patch(f"/api/workflows/{workflow_id}", json={"graph": graph}) + workflow_id, revision = draft.workflow_id, workflow.version + saved = await client.patch(f"/api/workflows/{workflow_id}", + json={"graph": graph, "expected_revision": revision}) assert saved.status_code == 200 and saved.json()["version"] == 2, saved.text missing = await client.post(f"/api/ledger/drafts/{draft_id}/trial", json={"inputs": {}}) @@ -520,7 +535,7 @@ async def test_trial_endpoint_returns_metric_values_from_the_run(client, documen res = await client.get(f"/api/ledger/drafts/{draft_id}/trial") assert res.status_code == 200, res.text body = res.json() - assert body == {"run_id": body["run_id"], "status": "succeeded", "version": 1, + assert body == {"run_id": body["run_id"], "status": "succeeded", "version": 1, "trial_id": body["trial_id"], "graph_hash": body["graph_hash"], "execution_hash": body["execution_hash"], "validation": body["validation"], "inputs_hash": body["inputs_hash"], "metrics": [{"id": "m1", "name": "已支付退款率", "rendered": "3.2%", "value": 0.032}], diff --git a/backend/tests/test_ledger_issue.py b/backend/tests/test_ledger_issue.py index 44b204a5..d2e855c9 100644 --- a/backend/tests/test_ledger_issue.py +++ b/backend/tests/test_ledger_issue.py @@ -5,7 +5,8 @@ 哈希,参数是绑定 + 缺省值,按 graph_hash 钉住;GET 账本的 actions 写能自动、issued 列出它;再点一次交回同一次; - 已发布级别、助手选用的、不是问数据的(画布试运行等):不自动,只给一键(写明为什么),一键照常发起;设置关了自动出具 也不自动; -- 拒绝写明原因:整题不等价、点名别的口径、版本退役、图里有人工节点、缺入口字段、超过每日上限、使用者没有应用授权; +- 拒绝写明原因:整题不等价、点名别的口径、版本退役、图里有人工节点、缺入口字段、绑定出来的参数这次没有值或缺声明、 + 取数模板认不出参数写在哪(参数完整性,ledger/params)、超过每日上限、使用者没有应用授权; 使用者有授权(应用固定着这一版)就能出具,origin 记靠的是哪个应用; - 设置 ledger 一组:缺省值、写坏了拒收。 数据是虚构店铺库。 @@ -49,6 +50,22 @@ async def client(): yield c +@pytest.fixture +def executed(monkeypatch) -> list[str]: + """这一次测试里真正发给数据库的语句(内联渲染之后的那一条),按先后:缺参数的那条路一条都不该有。""" + from app.tools import datasource + + seen: list[str] = [] + real = datasource.run_query + + async def spy(source, sql, **kw): + seen.append(sql) + return await real(source, sql, **kw) + + monkeypatch.setattr(datasource, "run_query", spy) + return seen + + async def reset_ledger(**values) -> None: async with SessionLocal() as session: row = await session.get(Setting, "ledger") @@ -386,9 +403,9 @@ async def test_auto_issue_goes_by_the_askers_permissions_when_login_is_on(monkey assert launched == formal.id and formal.started_by == f"erin_{row.id[:6]}" and formal.origin["auto"] is True -async def test_binding_values_that_would_break_the_sql_are_not_filled_in(client, monkeypatch): +async def test_binding_values_that_would_break_the_sql_are_not_filled_in(client, monkeypatch, executed): """绑定出来的值要渲染进口径的 SQL 模板:写在引号里的值带着引号(这次的 SQL 里写的是转义过的 '',绑定照原样取出)就不代填 - 出具——和组合时校验助手给的参数是同一个判断,宁可少出具。""" + 出具——和组合时校验助手给的参数是同一个判断,宁可少出具。没有发起的正式运行,也就没有多出来的查询。""" template = "SELECT SUM(amount) AS gmv FROM orders WHERE status = '{{ input.status }}'" graph = S.caliber_graph(template) graph["nodes"][0]["data"]["config"]["fields"] = [{"name": "status", "required": True}] @@ -400,5 +417,109 @@ async def test_binding_values_that_would_break_the_sql_are_not_filled_in(client, await ledger_match.drain() whole = (await ledger_match.store.latest(row.id)).content["whole"] assert whole["equivalent"] is True and whole["binding"] == {"status": "pa''id"} + sent = len(executed) res = await client.post(f"/api/ledger/answers/{row.id}/issue", json={"workflow_id": wf, "version": 1}) assert res.status_code == 409 and "不能有引号" in res.json()["detail"] and "不代填出具" in res.json()["detail"] + assert await issued(row.id) == [] and executed[sent:] == [] + + +async def test_entry_fields_this_binding_leaves_empty_are_not_filled_in(client, monkeypatch, executed): + """绑定出来的参数是空串(这次的 SQL 里写的就是 region = '')、这一版的入口又没声明缺省值:空串不是值,是省略,按参数 + 完整性(ledger/params,trial、组合式问数、派生各入口同一套)不代填出具——以前只查承载方式那一层,这里会按空串渲染, + 发起一次少了 region 这个条件的正式运行(缺参、未声明、零 SQL:一条都不发)。""" + template = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' AND region = '{{ input.region }}' " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") + graph = S.caliber_graph(template) + graph["nodes"][0]["data"]["config"]["fields"] = [ + {"name": "start", "required": True}, {"name": "end", "required": True}, {"name": "region"}] + wf = await S.publish(graph=graph, level="published") + two_writers(monkeypatch, "本周销售额 [[v:Q1.r0.销售额]]。") + run = await run_manager.start(graph=S.explore_graph( + "select sum(o.amount) as 销售额 from orders o where o.paid_at >= '2026-09-01' and o.status = 'paid' " + "and o.region = '' and o.paid_at < '2026-09-08'"), input_payload={}, origin_kind="canvas") + row = await S.wait(run.id) + await ledger_match.drain() + whole = (await ledger_match.store.latest(row.id)).content["whole"] + assert whole["equivalent"] is True and whole["binding"]["region"] == "" + sent = len(executed) + [action] = [a for a in (await client.get(f"/api/runs/{row.id}/ledger")).json()["actions"] if a["kind"] == "issue"] + assert action["available"] is False and "region" in action["reason"] + assert "missing_parameter" in action["reason"], action["reason"] + res = await client.post(f"/api/ledger/answers/{row.id}/issue", json={"workflow_id": wf, "version": 1}) + assert res.status_code == 409 and res.json()["code"] == ledger_issue.REFUSED + assert "missing_parameter" in res.json()["detail"] and "不代填出具" in res.json()["detail"] + assert await issued(row.id) == [] and executed[sent:] == [] + + +async def test_a_template_referencing_a_field_the_version_never_declared_is_not_filled_in(client, monkeypatch, executed): + """取数模板引用了入口没声明的参数:绑定出来的值没有对应的入口字段,按参数完整性(ledger/params)不代填出具——这种 + 模板渲染出来是空串,正式运行会照发。""" + template = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' AND region = '{{ input.region }}' " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") + graph = S.caliber_graph(template) + graph["nodes"][0]["data"]["config"]["fields"] = [{"name": "start", "required": True}, + {"name": "end", "required": True}] + wf = await S.publish(graph=graph, level="published") + two_writers(monkeypatch, "本周销售额 [[v:Q1.r0.销售额]]。") + run = await run_manager.start(graph=S.explore_graph( + "select sum(o.amount) as 销售额 from orders o where o.paid_at >= '2026-09-01' and o.status = 'paid' " + "and o.region = 'east' and o.paid_at < '2026-09-08'"), input_payload={}, origin_kind="canvas") + row = await S.wait(run.id) + await ledger_match.drain() + whole = (await ledger_match.store.latest(row.id)).content["whole"] + assert whole["equivalent"] is True and whole["binding"]["region"] == "east" + sent = len(executed) + res = await client.post(f"/api/ledger/answers/{row.id}/issue", json={"workflow_id": wf, "version": 1}) + assert res.status_code == 409 and res.json()["code"] == ledger_issue.REFUSED + assert "undeclared_parameter" in res.json()["detail"] and "不代填出具" in res.json()["detail"] + assert await issued(row.id) == [] and executed[sent:] == [] + + +#: 认不出参数写在哪的两种写法:入口字段和运行时变量混在一句里、参数写在表名(列名)里 +UNREADABLE_TEMPLATES = [ + "SELECT COUNT(*) AS n FROM orders WHERE region = '{{ input.store }}' AND note = '{{ vars.q }}'", + 'SELECT COUNT(*) AS n FROM "{{ input.store }}"', +] + + +@pytest.mark.parametrize("sql", UNREADABLE_TEMPLATES) +async def test_a_version_with_a_template_the_input_cannot_be_found_in_is_not_issued(client, monkeypatch, executed, sql): + """这一版里别的取数节点上的模板认不出参数写在哪:发起前就按参数完整性拒,不再当成「不归出具管」放过去——和 trial、 + 组合式问数、派生是同一个判断(口径那一张卡自己的取数模板这样写,在派生那一步就拒了)。 + + 这一版固定下来渲染不出确定的语句:{{ vars.q }} 会在正式运行里换成运行时的值、参数写进表名,出具的就不再是这一版口径 + 的取数了。以前跳过 unsupported_parameter 这一条,计划说能出具、真发起了才看出来。""" + graph = S.caliber_graph() + graph["nodes"].insert(2, S.node("extra", "tool", tool=S.tool(), args={"sql": sql})) + graph["edges"] = [{"source": a["id"], "target": b["id"]} for a, b in zip(graph["nodes"], graph["nodes"][1:])] + wf = await S.publish(graph=graph, level="published") + row = await equivalent_run(monkeypatch, origin="canvas") + sent = len(executed) + [action] = [a for a in (await client.get(f"/api/runs/{row.id}/ledger")).json()["actions"] if a["kind"] == "issue"] + assert action["available"] is False and "认不出参数写在哪" in action["reason"] + res = await client.post(f"/api/ledger/answers/{row.id}/issue", json={"workflow_id": wf, "version": 1}) + assert res.status_code == 409 and res.json()["code"] == ledger_issue.REFUSED + assert "认不出参数写在哪" in res.json()["detail"] and "不代填出具" in res.json()["detail"] + assert await issued(row.id) == [] and await settle(row.id) == [] and executed[sent:] == [] + + +@pytest.mark.parametrize("sql", UNREADABLE_TEMPLATES) +async def test_a_measured_template_the_input_cannot_be_found_in_is_not_filled_in(client, monkeypatch, executed, sql): + """口径自己的那张取数模板认不出参数写在哪时同样不代填出具(ledger/issue.check_target 这一个判法,出具和召回待办的 + 「按新版重新出具」共用)。 + + 这么写的模板比不出等价(比对也认不出参数写在哪),所以到不了「先有一次等价答案」那一路:直接按已经比对好的那份打算问 + 能不能发起,照实说原因;来源运行仍是真实跑出来的那一次,一条 SQL、一个正式运行都不该多出来。""" + graph = S.caliber_graph() + graph["nodes"][1]["data"]["config"]["args"]["sql"] = sql + wf = await S.publish(graph=graph, level="published") + row = await equivalent_run(monkeypatch, origin="canvas") + sent = len(executed) + content = {"whole": {"equivalent": True, "workflow_id": wf, "version": 1, "how": "independent", + "level": "published", "binding": {"start": "2026-09-01", "end": "2026-09-08"}}} + async with SessionLocal() as session: + plan = await ledger_issue.plan_issue(session, await session.get(Run, row.id), content, wf, 1, + principal=ADMIN) + assert plan.available is False and plan.status == 409 and plan.code == ledger_issue.REFUSED + assert "认不出参数写在哪" in plan.reason and "不代填出具" in plan.reason + assert await issued(row.id) == [] and executed[sent:] == [] diff --git a/backend/tests/test_ledger_nlchange.py b/backend/tests/test_ledger_nlchange.py new file mode 100644 index 00000000..970217f0 --- /dev/null +++ b/backend/tests/test_ledger_nlchange.py @@ -0,0 +1,1028 @@ +"""K12 受限的自然语言修改与固定请求路由(app/ledger/nlchange.py、api/ledger.py、api/copilot.py 的接缝)。 + +这份文件盯住这几条: + +1. **自然语言只产出 K03 同一份提案。** 一句话提到已声明能力(统计时间口径、退款处理)就落成 K03 同一形状的 operations, + 影响摘要和失效/绑定结论由 `changes.summary` 在同一批操作上现算——和表单路径同一份;一句话说不清(「排除退款」,词汇表 + 里只有「排除全额退款」和「全部计入」)就只给澄清项,一条操作也不产出,不替人猜、也不擅自改口径。 +2. **应用只有一条路。** 提案不落库;confirm=false 只预览;confirm=true 也只是薄适配,翻成一次 DraftPatchIn 交给现有 + 变更服务(patch_draft)——expected_revision / request_id / CAS / 绑定同步 / 校验一条不少,失败不擅自改口径。 +3. **模型只能提建议。** from_model 里的 operations 照样过 K03 的白名单和值域;actor / review / verified / approved 这类 + 自报批准的键一律丢掉,影响摘要和失效结论一律由平台现算。 +4. **Ask Data 固定请求路由。** 已经明确 workflow/card/metric_ids/inputs 的请求直接进 QueryCore(路线只把版本固定一次, + QueryCore 不再另挑一次,执行路径内部 LLM 仍为 0);没有匹配口径就进探索、含糊业务条件先澄清、请求里的业务条件和 + 匹配到的口径对不上就明确说「先改口径」——绝不静默换计算规则。 +5. **真实 HTTP 与权限。** 走真实接口,不连真实业务库(合成 SQLite 库);开登录后 user 角色调这几个接口是 403。 + +模型一律不调用(路由本身零模型:注入会炸的假模型);试跑/执行走真实引擎但只用合成库。 +""" +from __future__ import annotations + +import contextlib +import copy +import json +import uuid +from collections.abc import Mapping +from typing import Any + +import pytest +from fastapi import HTTPException +from sqlalchemy import delete, func, select + +from app.db.base import SessionLocal +from app.db.models import (CaliberDraft, CaliberWriteRequest, DataSource, Run, Workflow, WorkflowPublication, + WorkflowVersion) +from app.ledger import changes, nlchange +from tests import binding_samples as B +from tests.test_ledger_docdraft_api import client # noqa: F401 - fixture 和别的账本用例共用 +from tests.publication_samples import add_version, make_workflow, publish +from tests.test_querycore_execute import WINDOW_SUM # noqa: F401 - 合成库的独立预期 +from tests.test_querycore_execute import graph as qc_graph +from tests.test_querycore_execute import metrics as qc_metrics +from tests.test_querycore_execute import fresh_source as qc_source + +#: 这个文件自己建的工作流(连同版本、草稿、幂等记录、发布事件、数据源、应用)跑完删掉,不给别的用例留行 +OWN_PREFIX = "K12 " +_MADE: dict[str, list[str]] = {"workflows": [], "sources": [], "apps": []} + + +@pytest.fixture(autouse=True) +async def cleanup_own_rows(): + yield + async with SessionLocal() as session: + ids = list(_MADE["workflows"]) + if ids: + for model in (CaliberWriteRequest, CaliberDraft, WorkflowPublication, WorkflowVersion): + await session.execute(delete(model).where(model.workflow_id.in_(ids))) + await session.execute(delete(Workflow).where(Workflow.id.in_(ids))) + for name in _MADE["sources"]: + await session.execute(delete(DataSource).where(DataSource.name == name)) + if _MADE["apps"]: + from app.db.models_apps import App + + # 授权和应用版本都挂在应用上(ondelete=CASCADE):删应用就清干净 + await session.execute(delete(App).where(App.id.in_(list(_MADE["apps"])))) + _MADE["workflows"].clear() + _MADE["sources"].clear() + _MADE["apps"].clear() + await session.commit() + + +# ========================================================================== +# 1、一句话 → K03 提案(单元;不落库、不调模型) +# ========================================================================== + +def _order_graph(*, values: dict | None = None) -> dict: + """K04 的合成订单口径:两个共享一条受控模板 SQL 的指标,各自声明时间口径和退款规则。""" + return B.graph(values=values if values is not None else B.OLD) + + +def test_declared_capabilities_are_recognized_and_previewed(): + """「按支付时间统计,排除全额退款」→ 两个指标各两条 K03 操作,预览里定义变了、绑定能确定性同步。""" + graph = _order_graph() + proposal = nlchange.propose(graph, "card", "把订单口径改成按支付时间统计,排除全额退款") + assert proposal.ready and not proposal.clarifications + assert [(op["metric_id"], op["path"], op["value"]) for op in proposal.operations] == [ + ("m1", "/time_role", "payment_time"), ("m2", "/time_role", "payment_time"), + ("m1", "/refund_rule", "exclude_full_refund"), ("m2", "/refund_rule", "exclude_full_refund")] + assert proposal.metrics == ("m1", "m2") + preview = proposal.preview + assert preview["preview"] is True and preview["persisted"] is False and preview["applied"] is True + assert preview["classification"] == "definition" + assert preview["definition_hash"]["changed"] is True + assert preview["binding"]["status"] == "aligned" and preview["binding"]["synced"] is True + assert preview["binding"]["metrics"] == ["m1", "m2"] + # 预览不改原图:原图里那条 SQL 还是旧写法 + assert B.render(B.OLD) in str(graph) + + +def test_the_same_operations_from_nl_and_from_a_form_give_the_same_receipt(): + """同一批 operations,表单路径和自然语言路径在原图深拷贝上得到同一份回执(同一失效与绑定结论)。""" + graph = _order_graph() + proposal = nlchange.propose(graph, "card", "按支付时间统计,排除全额退款") + form_change = changes.apply_operations(graph, card_id="card", operations=list(proposal.operations)) + form_receipt = changes.summary(form_change, applied=bool(form_change.applied), revision=None) + preview = {key: value for key, value in proposal.preview.items() if key not in ("preview", "persisted")} + assert preview == form_receipt + + +def test_an_ambiguous_condition_is_clarified_and_produces_no_operations(): + """「排除退款」没区分全额/部分:先澄清,一条操作都不产出(不替人猜、不擅自改口径)。""" + proposal = nlchange.propose(_order_graph(), "card", "排除退款后重新算") + assert proposal.ready is False and proposal.operations == () and proposal.preview is None + [item] = proposal.clarifications + assert item.kind == nlchange.KIND_AMBIGUOUS and item.field == "refund_rule" + assert {option["value"] for option in item.options} == {"include_all", "exclude_full_refund"} + assert "排除全额退款" in item.question and "全部计入" in item.question + + +def _refund_rate_graph() -> dict: + """一张指标名里带「退款」的口径卡(退款率):名词里带「退款」不等于在谈退款规则。""" + metrics = B.card_metrics() + metrics[0]["name"] = "退款率" + metrics[0]["synonyms"] = ["退款比例"] + return B.graph(values=B.OLD, metrics=metrics) + + +def test_a_metric_name_containing_refund_does_not_ask_about_the_refund_rule(): + """「上个月退款率是多少」「把退款率改成按支付时间」不能因为指标名里有「退款」就误问退款处理。""" + graph = _refund_rate_graph() + # 只是问退款率:不是改口径,更不是问退款规则——澄清项是「没匹配到能力」,不是退款处理 + asked = nlchange.propose(graph, "card", "上个月退款率是多少") + assert asked.ready is False and [item.field for item in asked.clarifications] == [None] + assert asked.clarifications[0].kind == nlchange.KIND_NO_MATCH + # 改的是时间口径:只产出 time_role 的操作,不为指标名里的「退款」产出澄清项 + changed = nlchange.propose(graph, "card", "把退款率改成按支付时间") + assert changed.ready and not changed.clarifications + assert [(op["path"], op["value"]) for op in changed.operations] == [("/time_role", "payment_time")] * 2 + # 指标名在卡上(含同义词「退款比例」)时也一样:识别前先把指标名挖掉 + for text in ("退款比例改成按支付时间", "退款率按支付时间口径算"): + one = nlchange.propose(graph, "card", text) + assert one.ready and {op["path"] for op in one.operations} == {"/time_role"} + # 真的在谈退款规则时照旧识别/澄清 + assert nlchange.propose(graph, "card", "退款率改成排除全额退款").operations[0]["path"] == "/refund_rule" + # 指标名恰好是取值说法的一部分(「支付」)时不会被挖掉:「按支付时间」照旧认得出 + partial = B.card_metrics() + partial[0]["name"] = "支付" + shifted = nlchange.propose(B.graph(values=B.OLD, metrics=partial), "card", "支付这个口径改成按支付时间") + assert shifted.ready and {op["path"] for op in shifted.operations} == {"/time_role"} + + +def test_a_negated_exclusion_means_include_all_not_the_opposite(): + """「不要排除」「不排除」「无需排除全额退款」都是「全部计入」,绝不生成相反的「排除全额退款」。""" + for text in ("不要排除", "不排除", "无需排除全额退款", "不要排除全额退款", "不排除退款", "不排除退货"): + matches, clarifications = nlchange.match_conditions(text) + assert [(m.field, m.value) for m in matches] == [("refund_rule", "include_all")], text + assert clarifications == [], text + # 正着说的排除照旧是排除全额退款 + matches, clarifications = nlchange.match_conditions("排除全额退款") + assert [(m.field, m.value) for m in matches] == [("refund_rule", "exclude_full_refund")] + assert clarifications == [] + # 「排除退款」没分全额/部分:仍然澄清 + assert [item.field for item in nlchange.match_conditions("排除退款")[1]] == ["refund_rule"] + # 落成操作时也是 include_all(不是 exclude) + proposal = nlchange.propose(_order_graph(), "card", "把订单数改成不要排除退款") + assert {op["value"] for op in proposal.operations} == {"include_all"} + + +def test_other_negations_do_not_flip_to_the_opposite_value(): + """别的否定不倒过来认:「不按支付时间」不等于「按下单时间」,只报说不清。""" + for text in ("不按支付时间统计", "不要按下单时间", "取消按支付时间"): + matches, clarifications = nlchange.match_conditions(text) + assert matches == [], text + assert [item.field for item in clarifications] == ["time_role"], text + assert nlchange.propose(_order_graph(), "card", "不按支付时间统计").operations == () + + +def test_an_unrelated_sentence_is_clarified_not_silently_ignored(): + """没有提到任何已声明能力(更不是通用聊天 DSL):只给澄清项,不静默当成「不用改」。""" + proposal = nlchange.propose(_order_graph(), "card", "把销售额乘以二再上报") + assert proposal.ready is False + [item] = proposal.clarifications + assert item.kind == nlchange.KIND_NO_MATCH + assert {option["value"] for option in item.options} == {"time_role", "refund_rule"} + + +def test_a_model_suggestion_cannot_self_approve_or_write_forbidden_keys(): + """模型自报批准无效:actor / review / verified / approved 这类键一律丢掉,失效结论由平台现算。""" + graph = _order_graph() + payload = {"approved": True, "actor": "mallory", "verified": True, "summary": "不会失效", + "operations": [{"op": "set", "metric_id": "m1", "path": "/time_role", "value": "payment_time", + "reviewer": "mallory", "approved": True}]} + proposal = nlchange.from_model(graph, "card", payload) + assert proposal.ready + assert set(proposal.ignored_claims) >= {"approved", "actor", "verified", "summary", "reviewer"} + # 操作里只剩 K03 的四个键;自报的「批准」不在其中 + assert proposal.operations == ({"op": "set", "metric_id": "m1", "path": "/time_role", "value": "payment_time"},) + # 平台按图现算:改了定义,旧验证一律保守失效——模型说「不会失效」不算数 + assert proposal.preview["validation"]["invalidated"] is True + assert proposal.preview["applied"] is True + + +def test_a_model_suggested_operation_is_still_validated(): + """模型提的操作照样过白名单与值域:不认识的路径拒。""" + payload = {"operations": [{"op": "set", "metric_id": "m1", "path": "/definition/citations", "value": []}]} + with pytest.raises(changes.ChangeRefused) as caught: + nlchange.from_model(_order_graph(), "card", payload) + assert caught.value.code == changes.OPERATION_PATH + + +# ========================================================================== +# 2、HTTP:提案只读、confirm 才落版,且落回现有变更服务 +# ========================================================================== + +async def _order_draft() -> dict: + """一份已接管的订单口径草稿(K04 的合成图,形状同 docattach 的产物)。""" + body = await B.draft(_order_graph(), name=f"{OWN_PREFIX}订单口径") + _MADE["workflows"].append(body["workflow_id"]) + return body + + +async def versions_of(workflow_id: str) -> list[int]: + async with SessionLocal() as session: + return list((await session.execute(select(WorkflowVersion.version).where( + WorkflowVersion.workflow_id == workflow_id).order_by(WorkflowVersion.version))).scalars()) + + +async def graph_of(workflow_id: str) -> dict: + async with SessionLocal() as session: + workflow = await session.get(Workflow, workflow_id) + return copy.deepcopy(workflow.graph) + + +def fetch_config(graph: dict) -> dict: + return next(n for n in graph["nodes"] if n["id"] == "fetch")["data"]["config"] + + +async def test_the_change_proposal_endpoint_previews_and_only_applies_on_confirm(client): + """change-proposal 只读;nl-change 默认只预览;confirm=true 才落一版,且真的改到图上(定义 + 受控 SQL 一起)。""" + body = await _order_draft() + url = f"/api/ledger/drafts/{body['id']}" + + preview = await client.post(f"{url}/change-proposal", json={"instruction": "按支付时间统计,排除全额退款"}) + assert preview.status_code == 200, preview.text + proposal = preview.json()["proposal"] + assert proposal["ready"] and len(proposal["operations"]) == 4 + assert proposal["preview"]["binding"]["synced"] is True + assert await versions_of(body["workflow_id"]) == [1], "提案是只读的,不新增版本" + + draft_only = await client.post(f"{url}/nl-change", json={"instruction": "按支付时间统计,排除全额退款"}) + assert draft_only.status_code == 200, draft_only.text + assert draft_only.json()["applied"] is False and draft_only.json()["persisted"] is False + assert await versions_of(body["workflow_id"]) == [1], "默认不自动落版" + + applied = await client.post(f"{url}/nl-change", + json={"instruction": "按支付时间统计,排除全额退款", + "expected_revision": body["revision"], "confirm": True, + "request_id": "k12-0001"}) + assert applied.status_code == 200, applied.text + change = applied.json()["change"] + assert change["classification"] == "definition" and change["revision"] == 2 + assert await versions_of(body["workflow_id"]) == [1, 2] + graph = await graph_of(body["workflow_id"]) + config = fetch_config(graph) + assert config["args"]["sql"] == B.render(B.NEW), "受控模板按新业务值确定性展开" + assert config["binding"]["values"] == B.NEW and config["hints"] == {"keep": "me"} + + # 那句「按支付时间统计」说的话和真落库那条路同一次:批过的回执是补上的 + replay = await client.post(f"{url}/nl-change", + json={"instruction": "按支付时间统计,排除全额退款", + "expected_revision": body["revision"], "confirm": True, + "request_id": "k12-0001"}) + assert replay.status_code == 200 and replay.json()["replayed"] is True + assert await versions_of(body["workflow_id"]) == [1, 2], "同键重放不新增版本" + + +async def test_the_preview_matches_the_change_the_patch_returns(client): + """提案的预览和 PATCH 真落库的回执逐字段一致(除 revision / preview 标记)。""" + body = await _order_draft() + url = f"/api/ledger/drafts/{body['id']}" + proposal = (await client.post(f"{url}/change-proposal", + json={"instruction": "按支付时间统计,排除全额退款"})).json()["proposal"] + patch = await client.patch(url, json={"operations": proposal["operations"], + "expected_revision": body["revision"]}) + assert patch.status_code == 200, patch.text + change = patch.json()["change"] + preview = {key: value for key, value in proposal["preview"].items() if key not in ("preview", "persisted", + "revision")} + assert {key: value for key, value in change.items() if key != "revision"} == preview + + +async def test_an_ambiguous_instruction_over_http_writes_nothing(client): + """含糊业务条件:HTTP 回 409 + 澄清项,图一个字节都不动、不新增版本。""" + body = await _order_draft() + before = await graph_of(body["workflow_id"]) + res = await client.post(f"/api/ledger/drafts/{body['id']}/nl-change", + json={"instruction": "把退款排除掉", "expected_revision": body["revision"], + "confirm": True}) + assert res.status_code == 409, res.text + assert res.json()["code"] == nlchange.PROPOSAL_AMBIGUOUS + assert res.json()["clarifications"][0]["field"] == "refund_rule" + assert await versions_of(body["workflow_id"]) == [1] + assert await graph_of(body["workflow_id"]) == before, "失败不擅自改口径" + + +# ========================================================================== +# 3、Ask Data 固定请求路由 +# ========================================================================== + +async def _published_querycore_asset(*, graph: dict | None = None, version: int = 1) -> dict: + """一份已发布、有发布清单的固定口径(合成库),可以按固定口径执行。""" + asset = await make_workflow(graph=graph if graph is not None else qc_graph(), version=version) + _MADE["workflows"].append(asset["workflow_id"]) + return asset + + +@pytest.fixture +async def engine_up(tmp_path): + """执行走真实引擎(合成 SQLite 库)。""" + from app.engine.runner import run_manager + + await run_manager.setup() + name = await qc_source(tmp_path) + _MADE["sources"].append(name) + yield + await run_manager.shutdown() + + +def _no_model(monkeypatch) -> None: + """QueryCore / 路由内部 LLM = 0:任何模型调用都让这次执行炸掉。""" + from app.providers import mock_model + + def boom(self, messages): + raise AssertionError("固定请求路由与 QueryCore 不该调用模型") + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", boom) + + +async def runs_total() -> int: + async with SessionLocal() as session: + return int(await session.scalar(select(func.count(Run.id))) or 0) + + +async def test_a_determined_request_routes_to_querycore_and_executes(client, engine_up, monkeypatch): + """已经明确 workflow/card/metric_ids/inputs 的请求直接进 QueryCore:交回类型化结果,运行来源是口径固定执行。""" + _no_model(monkeypatch) + asset = await _published_querycore_asset() + await publish(client, asset) + metric_ids = [m["id"] for m in qc_metrics() if m["id"] in ("gmv", "units")] + + res = await client.post("/api/ledger/ask", json={ + "workflow_id": asset["workflow_id"], "card_id": "card", "metric_ids": metric_ids, + "inputs": {"start": "2026-09-01", "end": "2026-10-01"}}) + assert res.status_code == 200, res.text + body = res.json() + assert body["route"]["mode"] == nlchange.ROUTE_EXECUTE + assert body["route"]["request"]["version"] == 1 + result = body["result"] + assert result["ok"] is True and result["version"] == 1 + assert {m["id"]: m["value"] for m in result["metrics"]}["gmv"] == WINDOW_SUM + async with SessionLocal() as session: + run = await session.get(Run, result["run_id"]) + assert run.origin["service"] == "querycore" and run.origin["purpose"] == "compose" + + +async def test_a_pinned_version_is_not_resolved_again(client, engine_up): + """点名的那一版被固定下来:不重新挑推荐版、不重复规划(v2 的值和 v1 不同)。""" + asset = await _published_querycore_asset() + await publish(client, asset) + asset = await add_version(asset, qc_graph(sales_sql=( + "SELECT SUM(amount) AS gmv, SUM(qty) AS units, '合成标签' AS label FROM orders " + "WHERE status IN ('paid', 'open') AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'")), + version=2) + _MADE["workflows"].append(asset["workflow_id"]) + await publish(client, asset, version=2) + await publish(client, asset, version=1) # 推荐版回到 v1 + + named = await client.post("/api/ledger/ask", json={ + "workflow_id": asset["workflow_id"], "card_id": "card", "metric_ids": ["gmv"], "version": 2, + "inputs": {"start": "2026-09-01", "end": "2026-10-01"}}) + assert named.status_code == 200, named.text + assert named.json()["route"]["request"]["version"] == 2 + assert named.json()["result"]["version"] == 2 and named.json()["result"]["metrics"][0]["value"] != WINDOW_SUM + + followed = await client.post("/api/ledger/ask", json={ + "workflow_id": asset["workflow_id"], "card_id": "card", "metric_ids": ["gmv"], + "inputs": {"start": "2026-09-01", "end": "2026-10-01"}}) + assert followed.json()["route"]["request"]["version"] == 1 + assert followed.json()["result"]["metrics"][0]["value"] == WINDOW_SUM + + +async def test_a_decimal_string_version_is_a_pinned_version_not_the_recommended_one(client): + """fixed_request 里 version 写成十进制数字字符串时按**显式版本**处理:固定到那一版,不回退推荐版。""" + asset = await _published_querycore_asset() + await publish(client, asset) + asset = await add_version(asset, qc_graph(sales_sql=( + "SELECT SUM(amount) AS gmv, SUM(qty) AS units, '合成标签' AS label FROM orders " + "WHERE status IN ('paid', 'open') AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'")), + version=2) + _MADE["workflows"].append(asset["workflow_id"]) + await publish(client, asset, version=2) + await publish(client, asset, version=1) # 推荐版回到 v1 + + async with SessionLocal() as session: + pinned = await nlchange.route(session, request={ + "workflow_id": asset["workflow_id"], "card_id": "card", "metric_ids": ["gmv"], "version": "2", + "inputs": {"start": "2026-09-01", "end": "2026-10-01"}}) + followed = await nlchange.route(session, request={ + "workflow_id": asset["workflow_id"], "card_id": "card", "metric_ids": ["gmv"], + "inputs": {"start": "2026-09-01", "end": "2026-10-01"}}) + assert pinned.mode == nlchange.ROUTE_EXECUTE and pinned.request["version"] == 2 + assert followed.request["version"] == 1, "没写版本才读推荐版" + + +async def test_an_invalid_version_is_refused_not_silently_recommended(client): + """非法版本(不是正整数)先澄清/拒绝,绝不静默按推荐版执行。""" + asset = await _published_querycore_asset() + await publish(client, asset) + before = await runs_total() + async with SessionLocal() as session: + for bad, _why in (("abc", "文字"), ("2.5", "小数"), ("0", "零"), ("-1", "负数"), + ("", None), (None, None)): + routed = await nlchange.route(session, request={ + "workflow_id": asset["workflow_id"], "card_id": "card", "metric_ids": ["gmv"], + "version": bad, "inputs": {}}) + if _why is None: + assert routed.mode == nlchange.ROUTE_EXECUTE, bad + assert routed.request["version"] == 1, "空版本才读推荐版" + continue + assert routed.mode == nlchange.ROUTE_CLARIFY and routed.code == nlchange.ROUTE_VERSION_INVALID, bad + assert routed.request == {} and routed.clarifications[0].field == "version", bad + assert "整数" in routed.reason or "整数" in routed.clarifications[0].question, bad + assert await runs_total() == before, "非法版本不发起任何运行" + + +async def test_the_copilot_seam_clarifies_an_invalid_version(monkeypatch): + """接缝路径(fixed_request 原样传字典):非法版本先澄清,不静默换成推荐版。""" + _no_model(monkeypatch) + from app.api import copilot + + payload = copilot.GenerateIn(instruction="上个月销售额", intent="answer", + fixed_request={"workflow_id": "wf-x", "card_id": "card", + "metric_ids": ["m1"], "version": "abc"}) + ops = [op async for op in copilot.answer_ops(payload)] + assert len(ops) == 1 and ops[0]["op"] == "reply" + assert "整数" in ops[0]["text"] + + +async def test_the_copilot_seam_executes_a_decimal_string_version(client, engine_up, monkeypatch): + """接缝路径真的按十进制字符串版本固定执行:跑到 v2,不是推荐版 v1。""" + _no_model(monkeypatch) + from app.api import copilot + + asset = await _published_querycore_asset() + await publish(client, asset) + asset = await add_version(asset, qc_graph(sales_sql=( + "SELECT SUM(amount) AS gmv, SUM(qty) AS units, '合成标签' AS label FROM orders " + "WHERE status IN ('paid', 'open') AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'")), + version=2) + _MADE["workflows"].append(asset["workflow_id"]) + await publish(client, asset, version=2) + await publish(client, asset, version=1) # 推荐版回到 v1 + + payload = copilot.GenerateIn(instruction="上个月销售额", intent="answer", fixed_request={ + "workflow_id": asset["workflow_id"], "card_id": "card", "metric_ids": ["gmv"], "version": "2", + "inputs": {"start": "2026-09-01", "end": "2026-10-01"}}) + ops = [op async for op in copilot.answer_ops(payload) if op.get("op") != "heartbeat"] + [final] = ops + assert final["op"] == "final" and final["execution"]["ok"] is True + assert final["execution"]["metrics"][0]["value"] != WINDOW_SUM, "v2 把 open 也算进去,值应该不一样" + async with SessionLocal() as session: + run = await session.get(Run, final["run_id"]) + assert run.version == 2, "按点名的字符串版本固定执行,不是推荐版" + + +async def test_no_matching_caliber_goes_to_exploration(client, monkeypatch): + """指不到口径就明确进探索:不静默挑一份口径执行、也不发起任何运行。""" + _no_model(monkeypatch) + before = await runs_total() + res = await client.post("/api/ledger/ask", json={"workflow_id": "nope-not-a-workflow", "card_id": "card", + "metric_ids": ["gmv"]}) + assert res.status_code == 200, res.text + body = res.json() + assert body["route"]["mode"] == nlchange.ROUTE_EXPLORE + assert body["route"]["code"] == nlchange.ROUTE_NO_CALIBER and body["result"] is None + assert await runs_total() == before, "进探索不发起运行" + + +async def test_an_ambiguous_business_condition_clarifies_before_executing(client): + """含糊业务条件先澄清:不按旧口径静默执行、不发起运行。""" + before = await runs_total() + res = await client.post("/api/ledger/ask", json={"workflow_id": "wf-x", "card_id": "card", + "metric_ids": ["gmv"], "instruction": "排除退款"}) + assert res.status_code == 200, res.text + body = res.json() + assert body["route"]["mode"] == nlchange.ROUTE_CLARIFY + assert body["route"]["code"] == nlchange.ROUTE_AMBIGUOUS + assert body["route"]["clarifications"][0]["field"] == "refund_rule" + assert body["result"] is None and await runs_total() == before + + +async def test_a_contradicting_condition_does_not_swap_the_rule(client): + """请求里的业务条件和匹配到的口径对不上:明确进探索说「先改口径」,绝不静默换计算规则。""" + workflow_id = await B.publish(_order_graph(), name=f"{OWN_PREFIX}订单口径") + _MADE["workflows"].append(workflow_id) + before = await runs_total() + res = await client.post("/api/ledger/ask", json={"workflow_id": workflow_id, "card_id": "card", + "metric_ids": ["m1"], "instruction": "按支付时间统计"}) + assert res.status_code == 200, res.text + body = res.json() + assert body["route"]["mode"] == nlchange.ROUTE_EXPLORE + assert body["route"]["code"] == nlchange.ROUTE_CONDITION_MISMATCH + assert "不静默换计算规则" in body["route"]["reason"] + assert body["result"] is None and await runs_total() == before + + +async def test_missing_metric_ids_clarifies_instead_of_whole_card(client): + """没点名指标就先澄清:空的选择不静默当整卡。""" + workflow_id = await B.publish(_order_graph(), name=f"{OWN_PREFIX}订单口径") + _MADE["workflows"].append(workflow_id) + res = await client.post("/api/ledger/ask", json={"workflow_id": workflow_id, "card_id": "card"}) + assert res.status_code == 200, res.text + body = res.json() + assert body["route"]["mode"] == nlchange.ROUTE_CLARIFY + assert body["route"]["code"] == nlchange.ROUTE_METRICS_REQUIRED + assert {option["value"] for option in body["route"]["clarifications"][0]["options"]} == {"m1", "m2"} + + +async def test_the_copilot_seam_routes_a_fixed_request_without_a_model(monkeypatch): + """问数据那条路的接缝:带 fixed_request 时不经模型、不建图,直接交路由结论(含糊条件先澄清)。""" + _no_model(monkeypatch) + from app.api import copilot + + payload = copilot.GenerateIn(instruction="订单口径里排除退款之后是多少", intent="answer", + fixed_request={"workflow_id": "wf-x", "card_id": "card", + "metric_ids": ["m1"], "instruction": "排除退款"}) + ops = [op async for op in copilot.answer_ops(payload)] + assert len(ops) == 1 and ops[0]["op"] == "reply" + assert "排除全额退款" in ops[0]["text"] + + +# ========================================================================== +# 4、权限:开登录后这几个接口只给搭建者 +# ========================================================================== + +async def test_the_k12_endpoints_need_a_builder(): + from tests.fakes import auth_env + + await auth_env.reset() + admin = await auth_env.turn_on_local() + await auth_env.make_user("plain", role="user") + user = await auth_env.login("plain") + try: + ask = await user.post("/api/ledger/ask", json={"workflow_id": "x"}) + assert ask.status_code == 403, ask.text + proposal = await user.post(f"/api/ledger/drafts/{uuid.uuid4().hex}/change-proposal", + json={"instruction": "排除全额退款"}) + assert proposal.status_code == 403, proposal.text + ok = await admin.post("/api/ledger/ask", json={"workflow_id": "nope"}) + assert ok.status_code == 200, ok.text + finally: + await user.aclose() + await admin.aclose() + await auth_env.reset() + + +# ========================================================================== +# 5、普通问数的保守默认路由(K12):高置信才自动进 QueryCore,其余回旧路 +# ========================================================================== + +#: 自动路由专用的指标名:全局唯一(别的用例的指标名都不是它的子串,它也不含别人的名字) +AUTO_NAME = "自动路由专用净额甲" + + +def auto_graph(metric_name: str = AUTO_NAME, *, sales_sql: str | None = None, + fields: list[dict] | None = None) -> dict: + """把合成口径的 gmv 指标换成唯一名字,交给自动路由匹配用。""" + made = qc_graph(sales_sql=sales_sql) + start = next(n for n in made["nodes"] if n["id"] == "start") + if fields is not None: + start["data"]["config"]["fields"] = fields + card = next(n for n in made["nodes"] if n["id"] == "card") + card["data"]["config"]["metrics"][0]["name"] = metric_name + return made + + +async def _auto_asset(*, metric_name: str = AUTO_NAME, graph: dict | None = None, version: int = 1) -> dict: + asset = await make_workflow(graph=graph if graph is not None else auto_graph(metric_name), version=version) + _MADE["workflows"].append(asset["workflow_id"]) + return asset + + +def _answer(question: str) -> Any: + from app.api import copilot + + return copilot.GenerateIn(instruction=question, intent="answer") + + +def _fixed(asset: dict, **extra: Any) -> Any: + """一条已经明确的固定请求(Ask Data 的接缝):口径 + 卡 + 指标 + 入口取值。""" + from app.api import copilot + + request = {"workflow_id": asset["workflow_id"], "card_id": "card", "metric_ids": ["gmv"], + "inputs": {"start": "2026-09-01", "end": "2026-10-01"}, **extra} + return copilot.GenerateIn(instruction="上个月销售额是多少", intent="answer", fixed_request=request) + + +async def _ops(question: str) -> list[dict]: + from app.api import copilot + + return [op async for op in copilot.answer_ops(_answer(question)) if op.get("op") != "heartbeat"] + + +async def _answer_ops(payload: Any) -> list[dict]: + from app.api import copilot + + return [op async for op in copilot.answer_ops(payload) if op.get("op") != "heartbeat"] + + +@contextlib.contextmanager +def _acting(username: str, role: str = "user"): + """这一次请求是谁:开登录后的普通 user(restricted()),或者搭建者及以上。""" + from app.api import deps + + token = deps.set_principal(deps.Principal(username=username, role=role, verified=True, mode="local")) + try: + yield + finally: + deps.reset_principal(token) + + +async def _grant_app(workflow_id: str, version: int, *, who: str, role: str = "use") -> str: + """一份把这一版口径给这个使用者的应用:未归档、当前发布版钉住它,授权一条(AppGrant)。 + + 资产授权就是这么来的(app/apps/access.usable_calibers:授权给它的应用当前版本钉住的那些口径版本)。""" + from app.db.models_apps import App, AppGrant, AppVersion + + async with SessionLocal() as session: + app = App(name=f"{OWN_PREFIX}口径看板", draft={}, published_version=1) + session.add(app) + await session.flush() + pins = [{"alias": "main", "workflow_id": workflow_id, "version": version, "use": "view"}] + session.add(AppVersion(app_id=app.id, version=1, spec={"pins": pins}, spec_hash="x", pins=pins)) + session.add(AppGrant(app_id=app.id, principal_kind="user", principal=who, role=role)) + await session.commit() + _MADE["apps"].append(app.id) + return app.id + + +#: 普通 user 的操作里不该出现的**键**(口径身份、清单、选择、表、参数、查询与哈希) +_FORBIDDEN_KEYS = ("card_id", "workflow_id", "version", "publication", "manifest", "selection", "tables", + "parameters", "queries", "sql", "graph_hash", "hash") + + +def _no_internals(ops: list[dict], *, workflow_id: str) -> None: + """普通 user 拿到的操作里不该出现任何内部引用:口径身份、清单、选择、表、参数、查询与 SQL 正文。 + + 机器码(比如 querycore_manifest_required)不算内部引用:它给程序认,不带着任何身份或语句。""" + text = json.dumps(ops, ensure_ascii=False) + assert workflow_id not in text, f"操作里出现了工作流 id:{text}" + found = _keys_of(ops) & set(_FORBIDDEN_KEYS) + assert not found, f"操作里出现了内部字段:{found}" + assert "select " not in text.lower(), f"操作里出现了 SQL 正文:{text}" + +def _keys_of(value: Any) -> set[str]: + """这份操作里出现过的所有键(递归):按**键**判内部引用,不按子串判(机器码里带 manifest 不算泄露)。""" + if isinstance(value, Mapping): + found = {str(key) for key in value} + for item in value.values(): + found |= _keys_of(item) + return found + if isinstance(value, (list, tuple)): + found = set() + for item in value: + found |= _keys_of(item) + return found + return set() + + +@pytest.fixture +def model_unconfigured(monkeypatch): + """助手模型「没配好」:旧路径到这里会回 400;自动路由命中时根本不取模型。""" + from app.api import copilot + from app.providers.factory import ProviderNotConfigured + + async def boom(*a, **kw): + raise ProviderNotConfigured("测试里没有配助手模型") + + monkeypatch.setattr(copilot, "_op_model", boom) + return monkeypatch + + +async def test_a_unique_exact_metric_auto_routes_to_querycore_without_a_model(client, engine_up, monkeypatch): + """唯一精确指标:answer_ops 不经模型直接进 QueryCore,final 标出固定执行与 run_id/manifest/selection。""" + _no_model(monkeypatch) + asset = await _auto_asset() + await publish(client, asset) + + ops = await _ops(f"{AUTO_NAME} 2026年9月是多少") + assert len(ops) == 1, f"自动路由命中后不该再有别的操作:{ops}" + [final] = ops + assert final["op"] == "final" and final["execution"]["via"] == "querycore" + assert final["execution"]["ok"] is True and final["execution"]["version"] == 1 + assert final["execution"]["card_id"] == "card" and final["run_id"] + assert final["execution"]["publication"]["manifest"], "final 要带上这次固定口径的发布清单引用" + assert final["execution"]["selection"]["metric_ids"] == ["gmv"] + assert "QueryCore" in final["explanation"] + async with SessionLocal() as session: + run = await session.get(Run, final["run_id"]) + assert run.origin["service"] == "querycore" and run.origin["purpose"] == "compose" + + +async def test_a_single_month_and_a_single_day_map_to_the_half_open_window(client, engine_up, monkeypatch): + """明确完整的单月/单日映射到开始/结束字段(半开区间):单月整段、单日一天。""" + _no_model(monkeypatch) + asset = await _auto_asset() + await publish(client, asset) + + month = await _ops(f"{AUTO_NAME} 2026年9月是多少") + assert month[0]["execution"]["metrics"][0]["value"] == WINDOW_SUM + async with SessionLocal() as session: + first = await session.get(Run, month[0]["run_id"]) + assert first.input == {"start": "2026-09-01", "end": "2026-10-01"} + + day = await _ops(f"{AUTO_NAME} 2026-09-02 的数字") + [final] = day + assert final["execution"]["metrics"][0]["value"] == 100.0 + async with SessionLocal() as session: + second = await session.get(Run, final["run_id"]) + assert second.input == {"start": "2026-09-02", "end": "2026-09-03"} + + +async def test_a_name_shared_across_cards_is_ambiguous_and_falls_back(client, model_unconfigured): + """同名跨卡不自动:交回 None,answer_ops 照旧走旧路径(模型没配好时就照旧 400)。""" + shared = "同名歧义甲" + for _ in range(2): + asset = await _auto_asset(metric_name=shared) + await publish(client, asset) + async with SessionLocal() as session: + assert await nlchange.auto_route(session, question=f"{shared} 2026年9月是多少") is None + with pytest.raises(HTTPException) as caught: + await _ops(f"{shared} 2026年9月是多少") + assert caught.value.status_code == 400 + + +async def test_a_missing_non_date_parameter_falls_back(client, model_unconfigured): + """缺一个不能确定的非日期必填值(门店):不自动,回旧路径。""" + sql = ("SELECT SUM(amount) AS gmv, SUM(qty) AS units, '合成标签' AS label FROM orders " + "WHERE status = 'paid' AND store = '{{ input.store }}' " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") + fields = [{"name": "start", "type": "string", "required": True, "description": "开始日期(含)"}, + {"name": "end", "type": "string", "required": True, "description": "结束日期(不含)"}, + {"name": "store", "type": "string", "required": True, "description": "门店"}] + asset = await _auto_asset(graph=auto_graph(sales_sql=sql, fields=fields)) + await publish(client, asset) + async with SessionLocal() as session: + assert await nlchange.auto_route(session, question=f"{AUTO_NAME} 2026年9月是多少") is None + with pytest.raises(HTTPException) as caught: + await _ops(f"{AUTO_NAME} 2026年9月是多少") + assert caught.value.status_code == 400 + + +async def test_an_unmatched_question_still_takes_the_old_path_for_an_ordinary_user(client, engine_up, + model_unconfigured): + """普通 user 也走这条接缝:**没匹配到**口径的话照旧走旧路径(模型没配好时照旧 400)。 + + 新契约:普通 user 不再一律回旧路——命中了授权范围内的口径就按口径取数(见下面几条),这里盯的是「没匹配到」那 + 一半仍旧回旧路。""" + asset = await _auto_asset() + await publish(client, asset) + await _grant_app(asset["workflow_id"], 1, who="plain") + with _acting("plain"): + with pytest.raises(HTTPException) as caught: + await _ops("跟我们说说最近有什么值得关注的变化") + assert caught.value.status_code == 400 + # 换成搭建者及以上(关登录就是 admin)照旧自动命中 + builder = await _ops(f"{AUTO_NAME} 2026年9月是多少") + assert builder[0]["execution"]["via"] == "querycore" + + +async def test_auto_route_refuses_a_unique_hit_outside_the_allowed_set(client): + """授权闸在 auto_route 这一层:唯一命中却不在 allowed 里交回**终止型** ROUTE_REFUSED。 + + 这不是「未匹配」(未匹配才是 None,那会被调用方当成没匹配到、照旧走旧 Agent 路径去翻底表);授的是别的版本不算数; + allowed 为 None 是调用方已放行(搭建者及以上)。""" + asset = await _auto_asset() + await publish(client, asset) + question = f"{AUTO_NAME} 2026年9月是多少" + async with SessionLocal() as session: + refused = await nlchange.auto_route(session, question=question, allowed=set()) + assert refused.mode == nlchange.ROUTE_REFUSED and refused.code == nlchange.ROUTE_NOT_PERMITTED + assert refused.request == {} and refused.reason == nlchange.NOT_PERMITTED + assert asset["workflow_id"] not in refused.reason, "拒绝的说法里不出现内部 id" + # 授权范围里没有这一版(授的是别的版本):同样拒绝,绝不静默按推荐版执行 + other = await nlchange.auto_route(session, question=question, allowed={(asset["workflow_id"], 2)}) + assert other.mode == nlchange.ROUTE_REFUSED + # 授权范围里有这一版:照旧交回固定请求 + hit = await nlchange.auto_route(session, question=question, allowed={(asset["workflow_id"], 1)}) + assert hit.mode == nlchange.ROUTE_EXECUTE and hit.request["version"] == 1 + assert hit.request["metric_ids"] == ["gmv"] + # allowed 为 None:调用方已放行,不做这道闸 + opened = await nlchange.auto_route(session, question=question) + assert opened.mode == nlchange.ROUTE_EXECUTE + # 真含糊(不是「命中但无权」):照样交回 None,调用方走旧路 + assert await nlchange.auto_route(session, question="排除退款后的" + question, allowed=set()) is None + + +async def test_a_hit_without_a_grant_is_refused_and_never_explores_the_tables(client, engine_up, + model_unconfigured): + """命中了但这个人没有使用权:终止型结局(route_not_permitted / next=fail),不发起运行,也不回退旧 Agent 路径。 + + 「不回退」是可证的:模型没配好,一旦落到旧路径就一定会 400——这里拿到的是 error 操作,不是 400。""" + asset = await _auto_asset() + await publish(client, asset) + before = await runs_total() + with _acting("plain"): + ops = await _ops(f"{AUTO_NAME} 2026年9月是多少") + [failed] = ops + assert failed["op"] == "error" and failed["code"] == nlchange.ROUTE_NOT_PERMITTED + assert failed["next"] == "fail" and "没有授权" in failed["message"] + assert await runs_total() == before, "没授权不发起任何运行(更不翻底表)" + _no_internals(ops, workflow_id=asset["workflow_id"]) + + +async def test_an_authorised_user_asks_without_a_canvas_and_gets_the_caliber_answer(client, engine_up, monkeypatch): + """授权 user 没有画布也按口径取数:走 prepare 好的父图 + 真实 caliber_query 工具,遮罩与只读由那条路保证。""" + _no_model(monkeypatch) + from app.ledger.querycore import CALIBER_QUERY + from app.tools.datasource import MASK_RESULTS_OPTION, READ_ONLY_OPTION + + asset = await _auto_asset() + await publish(client, asset) + await _grant_app(asset["workflow_id"], 1, who="plain") + with _acting("plain"): + ops = await _ops(f"{AUTO_NAME} 2026年9月是多少") + [final] = ops + assert final["op"] == "final" and final["execution"]["via"] == "querycore" + assert final["execution"]["status"] == "succeeded" + assert {m["name"]: m["value"] for m in final["execution"]["metrics"]} == {AUTO_NAME: WINDOW_SUM} + async with SessionLocal() as session: + run = await session.get(Run, final["run_id"]) + assert run.started_by == "plain", "运行记在发起的使用者名下" + assert run.options.get(MASK_RESULTS_OPTION) is True, "使用者的取数一律在工具边界遮" + assert run.options.get(READ_ONLY_OPTION) is True + assert CALIBER_QUERY in json.dumps(run.graph, ensure_ascii=False), "父图里绑的是真实口径工具" + _no_internals(ops, workflow_id=asset["workflow_id"]) + + +async def test_compose_does_not_need_a_formal_review(client, engine_up, monkeypatch): + """普通问数是 compose:这一版没有验证记录、没有认证审阅,照样按口径取数(formal 才要那一份依据)。""" + _no_model(monkeypatch) + from app.apps import publications + + asset = await _auto_asset() + await publish(client, asset) + await _grant_app(asset["workflow_id"], 1, who="plain") + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged is not None and judged.refusal is not None, "这一版没有验证审阅:正式用途一定拒" + with _acting("plain"): + ops = await _ops(f"{AUTO_NAME} 2026年9月是多少") + [final] = ops + assert final["op"] == "final" and final["execution"]["via"] == "querycore", ops + + +async def test_a_fixed_request_goes_through_the_same_gate(client, engine_up, monkeypatch): + """fixed_request 对普通 user 走**同一道授权闸**:没授权既不执行也不降级 Agent,有授权才按口径执行(带遮罩)。""" + _no_model(monkeypatch) + from app.tools.datasource import MASK_RESULTS_OPTION + + asset = await _auto_asset() + await publish(client, asset) + payload = _fixed(asset) + before = await runs_total() + with _acting("plain"): + refused = await _answer_ops(payload) + [failed] = refused + assert failed["op"] == "error" and failed["code"] == nlchange.ROUTE_NOT_PERMITTED + assert failed["next"] == "fail" and "没有授权" in failed["message"] + assert await runs_total() == before + _no_internals(refused, workflow_id=asset["workflow_id"]) + + await _grant_app(asset["workflow_id"], 1, who="plain") + with _acting("plain"): + allowed = await _answer_ops(payload) + [final] = allowed + assert final["op"] == "final" and final["execution"]["via"] == "querycore" + assert {m["name"]: m["value"] for m in final["execution"]["metrics"]} == {AUTO_NAME: WINDOW_SUM} + async with SessionLocal() as session: + run = await session.get(Run, final["run_id"]) + assert run.started_by == "plain" and run.options.get(MASK_RESULTS_OPTION) is True + _no_internals(allowed, workflow_id=asset["workflow_id"]) + + +async def test_a_manifest_failure_after_a_hit_is_reported_not_degraded(client): + """命中之后执行失败(这一版没有发布清单):原样报错,不静默回退旧 Agent。""" + from app.ledger import querycore + + workflow_id = await B.publish(auto_graph("无清单口径甲"), name=f"{OWN_PREFIX}无清单口径") + _MADE["workflows"].append(workflow_id) + ops = await _ops("无清单口径甲 2026年9月是多少") + [op] = ops + assert op["op"] == "error" and op["code"] == querycore.MANIFEST_REQUIRED, ops + assert op["next"] == "fail", "命中了就不再回旧路径,也不重来" + + +async def test_a_manifest_failure_after_a_hit_does_not_switch_paths_for_a_user(client, engine_up): + """同一件事对普通 user:终止型结局 + 安全白话(内部原话里带着工作流 id 与版本号,不外发)。""" + from app.api import copilot + + workflow_id = await B.publish(auto_graph("无清单口径乙"), name=f"{OWN_PREFIX}无清单口径乙") + _MADE["workflows"].append(workflow_id) + await _grant_app(workflow_id, 1, who="plain") + with _acting("plain"): + ops = await _ops("无清单口径乙 2026年9月是多少") + [op] = ops + assert op["op"] == "error" and op["next"] == "fail", ops + assert op["code"], "机器码照旧给,程序据此认这一档" + assert op["message"] == copilot.USER_FAILED, "只给安全白话,不把内部原话外发" + _no_internals(ops, workflow_id=workflow_id) + + +async def test_a_metric_whose_name_contains_refund_does_not_trip_the_refund_rule(client, engine_up, monkeypatch): + """指标名里带「退款」不影响自动路由;但问题里真带上含糊的退款条件就不自动(回旧路径)。""" + _no_model(monkeypatch) + asset = await _auto_asset(metric_name="退款率自动甲") + await publish(client, asset) + hit = await _ops("退款率自动甲 2026年9月是多少") + assert hit[0]["execution"]["via"] == "querycore" + async with SessionLocal() as session: + assert await nlchange.auto_route(session, question="排除退款后的退款率自动甲 2026年9月是多少") is None + + +async def test_the_model_not_configured_still_executes_a_determined_request(client, engine_up, model_unconfigured): + """模型没配好也照样执行确定请求;同一份设置下不指向任何口径的话照旧 400(旧路径)。""" + asset = await _auto_asset() + await publish(client, asset) + ops = await _ops(f"{AUTO_NAME} 2026年9月是多少") + [final] = ops + assert final["op"] == "final" and final["execution"]["ok"] is True + with pytest.raises(HTTPException) as caught: + await _ops("跟我们说说最近有什么值得关注的变化") + assert caught.value.status_code == 400 + + +def defaulted_graph(metric_name: str = AUTO_NAME) -> dict: + """口径卡的开始/结束日期字段声明了缺省值:不给日期时也拿得全(「查一下销售额」这类问法用它)。""" + made = auto_graph(metric_name) + start = next(n for n in made["nodes"] if n["id"] == "start") + for field in start["data"]["config"]["fields"]: + if field["name"] == "start": + field["default"] = "2026-09-01" + elif field["name"] == "end": + field["default"] = "2026-10-01" + return made + + +def empty_window_graph(metric_name: str = AUTO_NAME) -> dict: + """这一版声明「缺输入按空值算」:窗口里没有数据时跑完了但指标没有值(跑成功 ≠ 算成了)。""" + made = auto_graph(metric_name) + card = next(node for node in made["nodes"] if node["id"] == "card") + card["data"]["config"]["on_missing"] = "null" + return made + + +def test_the_remainder_keeps_only_the_business_semantics(): + """拆完之后剩下的只有业务语义:通用问法/查询/统计措辞与完整日期都去掉,别的一个字不动。""" + assert nlchange._auto_remainder("2026年10月销售额是多少", []) == "销售额" + assert nlchange._auto_remainder("查一下销售额", []) == "销售额" + assert nlchange._auto_remainder("2026-10-01 的销售额", []) == "销售额" + # 指标名一字不差是有边界的:多一个分析意图词、或者一个相对说法,都不是「销售额」 + assert nlchange._auto_remainder("销售额增长率是多少", []) == "销售额增长率" + assert nlchange._auto_remainder("销售额占比", []) == "销售额占比" + assert nlchange._auto_remainder("上个月销售额是多少", []) == "上个月销售额" + # 分析意图词刻意不算通用措辞(列在 _AUTO_ANALYSIS_WORDS 里,只为让人看到这条边界) + assert not set(nlchange._AUTO_ANALYSIS_WORDS) & set(nlchange._AUTO_FILLERS) + + +@pytest.mark.parametrize("extra", ["增长率", "占比", "同比", "环比", "趋势", "明细", "排行", "拆解"]) +async def test_an_extra_analysis_intent_falls_back_to_the_old_path(client, engine_up, model_unconfigured, extra): + """「销售额增长率/占比/趋势…」这类带额外分析意图的问法不直达:剩下的话和指标名不等,回旧路径。""" + asset = await _auto_asset() + await publish(client, asset) + for question in (f"{AUTO_NAME}{extra}是多少", f"{AUTO_NAME}的{extra}"): + async with SessionLocal() as session: + assert await nlchange.auto_route(session, question=question) is None, question + with pytest.raises(HTTPException) as caught: + await _ops(f"{AUTO_NAME}的{extra}是多少") + assert caught.value.status_code == 400 + + +async def test_natural_questions_use_declared_defaults_when_no_date_is_given(client, engine_up, monkeypatch): + """「查一下销售额」这类自然问法拆完就是指标名:日期没给、但字段声明了缺省值时照旧直达。""" + _no_model(monkeypatch) + asset = await _auto_asset(graph=defaulted_graph()) + await publish(client, asset) + for question in ("查一下" + AUTO_NAME, "帮我看看" + AUTO_NAME + "是多少", AUTO_NAME, + "2026年10月" + AUTO_NAME + "是多少"): + ops = await _ops(question) + assert len(ops) == 1 and ops[0]["op"] == "final", question + assert ops[0]["execution"]["via"] == "querycore", question + async with SessionLocal() as session: + first = await session.get(Run, (await _ops("查一下" + AUTO_NAME))[0]["run_id"]) + assert first.input == {"start": "2026-09-01", "end": "2026-10-01"}, "没给日期就用声明的缺省值" + # 相对说法(上个月)不是「销售额」:即使字段有缺省值也不直达 + async with SessionLocal() as session: + assert await nlchange.auto_route(session, question=f"上个月{AUTO_NAME}是多少") is None + + +async def test_a_hit_that_produces_nothing_is_reported_as_a_failure_for_a_user(client, engine_up, monkeypatch): + """命中之后「跑完了但没算成」(这一版声明缺输入按空值算、窗口里没有数据):普通 user 也拿到终止型结局 + 安全白话。 + + 这条盯的是 ok=False 那一档:运行是发生了,但一个可用的数也没有,不能当成给了答案,也不换路。""" + _no_model(monkeypatch) + from app.api import copilot + + asset = await _auto_asset(graph=empty_window_graph()) + await publish(client, asset) + await _grant_app(asset["workflow_id"], 1, who="plain") + with _acting("plain"): + ops = await _ops(f"2030年1月{AUTO_NAME}是多少") + [op] = ops + assert op["op"] == "error" and op["code"] == copilot.RESULT_FAILED, ops + assert op["next"] == "fail" and op["message"] == copilot.USER_FAILED + assert op["execution"]["status"] == "succeeded", "运行跑完了,只是没算成" + assert op["execution"]["run_id"] + _no_internals(ops, workflow_id=asset["workflow_id"]) + diff --git a/backend/tests/test_ledger_recall.py b/backend/tests/test_ledger_recall.py index 5610451a..5ae51c02 100644 --- a/backend/tests/test_ledger_recall.py +++ b/backend/tests/test_ledger_recall.py @@ -7,8 +7,8 @@ - 召回运行:派生图里新旧两版的取数和口径卡各一份(前缀不撞),召回卡里算两版之差;同一份数据上两版各算一次; - 收尾:数变了才开 recall 待办(挂在召回运行上,旧值、新值、差值、原答案当时的值都给),推 ledger.recall,消息里没有数; 数没变的在原答案上记 ledger.recalled(已按 vN 核对,不影响),不开待办; -- 不能重算的照实记:新版入口要的参数这一组里没有、图里会写外部系统;图里别处有人工节点的照样重算(召回图碰不到它), - 只是「按新版重新出具」不代人审批; +- 不能重算的照实记:新版入口要的参数这一组里没有、旧版一侧的同一个问题(旧版取数要的参数绑出来是空串)、图里会写外部 + 系统;图里别处有人工节点的照样重算(召回图碰不到它),只是「按新版重新出具」不代人审批; - 待办「按新版重新出具」走按口径出具同一套判法、「知道了」; - 目录里影响数字的一项被改了:冻结目录里看得到它的答案标「依据有变」,按新目录多出错误级问题的才开待办; - 表结构变了:用过这张表的答案标「依据的表结构已变」,口径试算算不出来才开待办; @@ -59,6 +59,22 @@ async def client(): yield c +@pytest.fixture +def executed(monkeypatch) -> list[str]: + """这一次测试里真正发给数据库的语句(内联渲染之后的那一条),按先后:参数不完整的那条路一条都不该有。""" + from app.tools import datasource + + seen: list[str] = [] + real = datasource.run_query + + async def spy(source, sql, **kw): + seen.append(sql) + return await real(source, sql, **kw) + + monkeypatch.setattr(datasource, "run_query", spy) + return seen + + async def ledger_settings(**values) -> None: async with SessionLocal() as session: row = await session.get(Setting, "ledger") @@ -303,6 +319,45 @@ async def test_incompatible_entry_and_side_effects_are_not_recomputed(monkeypatc assert view["can_continue"] is False +async def test_an_old_side_parameter_this_group_has_no_value_for_is_not_recomputed(monkeypatch, executed): + """旧版的取数模板要的参数这一组里没有值(这一组的 SQL 里写的就是 region = '',空串不是值;旧版又没声明缺省值): + + 计划就照实记「无法重算」,不写「可重算」等召回运行起飞了才失败——不然「还剩几组没算」永远算不完,也看不出为什么。 + 运行时那道兜底照旧在:真按这份计划发起一组,运行的两版取数在发查询前再判一次,一条 SQL 都不发。""" + sql = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' AND region = '{{ input.region }}' " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") + v1 = S.caliber_graph(sql) + v1["nodes"][0]["data"]["config"]["fields"] = [ + {"name": "start", "required": True}, {"name": "end", "required": True}, {"name": "region"}] + wf = await S.publish(graph=v1) + await S.explore(monkeypatch, "select sum(o.amount) as 销售额 from orders o where o.paid_at >= '2026-09-01' " + "and o.status = 'paid' and o.region = '' and o.paid_at < '2026-09-08'", + text="本周销售额 [[v:Q1.r0.销售额]]。", origin="chat") + await publish_v2(wf) # v2 的取数已经不带 region 了:只有旧版一侧要这个参数 + async with SessionLocal() as session: + plan = await recall.build_plan(session, wf, 2) + [group] = plan.groups + assert group.binding == {"start": "2026-09-01", "end": "2026-09-08"} + assert group.problem == ("旧版 v1 的入口要的参数这一组里没有或不合规:参数「region」这次没有值:" + "入口字段没给值、也没有缺省值,不能当空串用(missing_parameter)"), group.problem + assert plan.todo() == [] and await recall.launch(wf, 2) == [] + async with SessionLocal() as session: + view = await recall.batches(session, wf, 2) + assert await recall.recall_runs(session, wf, 2) == [] + assert view["counts"]["not_recomputable"] == 1 and view["can_continue"] is False + assert view["groups"][0]["reason"] == group.problem + async with SessionLocal() as session: + preview = await recall.preview(session, wf, 2) + assert preview["not_recomputable"] == 1 and preview["recomputable"] == 0 + assert preview["reasons"] == [{"reason": group.problem, "groups": 1}] + + # 兜底还在:照这份计划真发起一次,运行在发查询前被参数完整性拦下(零 SQL) + graph, _ = recall.build_graph(group, plan.pairs[group.old_version]) + sent = len(executed) + row = await S.wait((await run_manager.start(graph=graph.graph, input_payload=dict(group.inputs))).id) + assert row.status == "failed" and "region" in row.error and "missing_parameter" in row.error, row.error + assert executed[sent:] == [] + async def test_human_node_elsewhere_still_recomputes_but_reissue_refuses(client, monkeypatch): """新版图里在口径卡下游有审批(取数 → 口径卡 → 报告 → 人工确认 → 出口):召回图只有两版的取数和口径卡,人工节点碰不到, diff --git a/backend/tests/test_ledger_reconcile.py b/backend/tests/test_ledger_reconcile.py index 432ad856..b71bf789 100644 --- a/backend/tests/test_ledger_reconcile.py +++ b/backend/tests/test_ledger_reconcile.py @@ -10,11 +10,16 @@ """ from __future__ import annotations +import contextlib +from pathlib import Path +from types import SimpleNamespace + import pytest from httpx import ASGITransport, AsyncClient +from sqlalchemy import delete -from app.db.base import SessionLocal -from app.db.models import Run +from app.db.base import SessionLocal, utcnow +from app.db.models import Run, Workflow, WorkflowVersion from app.engine.runner import run_manager from app.engine.schema import GraphSpec, validate_graph from app.ledger import match as ledger_match @@ -158,6 +163,10 @@ async def test_multi_row_answers_are_aligned_by_their_dimensions(client, monkeyp assert done.origin["rows"] == [0, 1] and done.origin["pairs"] == [{"ours": "gmv", "caliber": "gmv"}] align = next(n for n in done.graph["nodes"] if n["id"] == "align") assert align["type"] == "merge" and align["data"]["config"]["inputs"] == {"o": "ours_q1", "c": "fetch"} + # 对齐语句是服务端拼的字面 SQL:带参数契约(哈希与这条语句绑定),运行时不再当模板渲染(值里的 {{ }} 是数据) + from app.ledger import params + + assert params.literal_keys(align["data"]["config"], "merge") == ("sql",) metrics = await card_of(done.id) assert metrics["ours_0_0"]["name"] == "区域=east · gmv · 这次" assert (metrics["ours_0_0"]["value"], metrics["cal_0_0"]["value"], metrics["diff_0_0"]["value"]) == (163.0, 150.5, 12.5) @@ -192,6 +201,25 @@ def test_align_sql_keeps_the_referenced_rows_in_order(): 'ORDER BY CASE WHEN (o."区域" = \'west\') THEN 0 WHEN (o."区域" = \'o\'\'east\') THEN 1 END') +def test_the_align_node_carries_a_literal_parameter_contract(): + """对齐语句由服务端按维度值拼成字面 SQL,值直接来自查询结果(可能就带 {{ }}):节点带参数契约(与这条语句绑定哈希), + 运行时的模板渲染不再碰它(K01:渲染一遍就是把数据当模板解释)。""" + from app.ledger import derive, params + + plan = ledger_reconcile.Plan(pairs=[ledger_reconcile.Pair(ours="gmv", column="gmv")], rows=[0], + keys=[("区域", "区域")], key_values=[("{{ vars.region }}",)]) + [align] = [n for n in ledger_reconcile.tail_nodes(plan, card_id="card", fetch_id="fetch") + if n["id"] == derive.ALIGN_ID] + config = align["data"]["config"] + assert "'{{ vars.region }}'" in config["sql"] + assert params.mode_of(config) == params.LITERAL_ARGS + # 核对过哈希才算数:这条语句和契约注解的就是同一条 + assert params.literal_keys(config, "merge") == ("sql",) + # 改过 SQL 之后契约作废(复制后编辑那条路) + edited = {**config, "sql": config["sql"] + " -- 改过"} + assert params.literal_keys(edited, "merge") == () + + async def test_users_reconcile_their_own_answers_read_only_and_masked(client, monkeypatch): """拍板 L5:对账(只读的探索运行)使用者都可以,带上问数据同一套 MASK_RESULTS / READ_ONLY;别人的答案读不到就不给对。""" from app.api.deps import Principal @@ -217,11 +245,12 @@ async def test_users_reconcile_their_own_answers_read_only_and_masked(client, mo async def test_users_read_their_reconcile_runs_only_through_the_evidence(client, monkeypatch): - """使用者发起的对账运行带 MASK_RESULTS、记在他名下,但派生图里有口径取数节点的 SQL 模板(口径的 SQL 可能写着遮罩值, - 所以问数据里使用者不看口径、不能 use_caliber):运行的原始记录、事件、运行时的图(/api/runs/{id}、/events、/graph)只给 - 他自己的问数据运行,对账运行经证据接口读(那里按遮罩渲染)。""" + """使用者发起的对账运行带 MASK_RESULTS、记在他名下,但派生图里有口径取数节点的 SQL 模板(口径的 SQL 可能写着遮罩值): + 运行的原始记录、事件、运行时的图(/api/runs/{id}、/events、/graph)只给他自己的问数据运行,对账运行经证据接口读 + (那里按遮罩渲染)。要让对账真的跑起来,他先得有那一版口径的资产授权(K14:缺了在发起前就 403,见下面那几条用例)。""" from app.tools.datasource import MASK_RESULTS_OPTION from tests.fakes import auth_env + from tests.test_caliber_query_tool import grant_caliber wf = await S.publish() row = await S.explore(monkeypatch, S.WITH_REFUNDS, origin="chat") @@ -232,11 +261,14 @@ async def test_users_read_their_reconcile_runs_only_through_the_evidence(client, await session.commit() [action] = [a for a in (await ledger_of(client, row.id))["actions"] if a["kind"] == "reconcile"] await auth_env.reset() + app_id = "" try: admin = await auth_env.turn_on_local() await auth_env.make_user("carol", "user") assert (await admin.put("/api/auth/settings", json={"user_can_chat": True})).status_code == 200 carol = await auth_env.login("carol") + # 对账要执行的就是这一版口径:先把这一版的资产授权给它(K14) + app_id = await grant_caliber(wf, 1, "carol", "use") res = await carol.post(f"/api/ledger/answers/{row.id}/reconcile", json={ "query": action["query"], "workflow_id": wf, "version": 1, "inputs": CHECKED, "confirm": True}) assert res.status_code == 201, res.text @@ -248,6 +280,12 @@ async def test_users_read_their_reconcile_runs_only_through_the_evidence(client, assert (await carol.get(f"/api/runs/{done.id}/evidence")).status_code == 200 finally: await auth_env.reset() + if app_id: + from app.db.models_apps import App + + async with SessionLocal() as session: + await session.execute(delete(App).where(App.id == app_id)) + await session.commit() async def test_the_reconcile_view_gives_the_panel_what_it_draws(client, monkeypatch): @@ -297,3 +335,243 @@ async def test_a_related_query_prefills_the_pairing_from_the_cells_that_were_pro assert res.status_code == 409 and res.json()["code"] == ledger_reconcile.NEEDS_PAIRS, res.text options = res.json()["options"] assert options["suggested"] == [{"ours": "gmv", "metric": "gmv"}], options + + +# ========================================================================== +# 普通使用者的资产授权(K14):对账要执行的那一版口径缺授权时,一条运行都不起 +# ========================================================================== + + +async def _answer_by(monkeypatch, who: str, sql: str = S.WITH_REFUNDS) -> Run: + """这个人自己发起的一次探索运行(对账要读它,相关口径也记在它的比对工件里):等封存、等后台比对做完。""" + from app.engine.runner import run_manager + from app.ledger import match as ledger_match + + S.script(monkeypatch, "本周销售额 [[v:Q1.r0.gmv]]。") + run = await run_manager.start(graph=S.explore_graph(sql), input_payload={}, run_class="exploratory", + origin_kind="chat", started_by=who) + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + await ledger_match.drain() + return row + + +async def _actions(client, run_id: str) -> list[dict]: + res = await client.get(f"/api/runs/{run_id}/ledger") + assert res.status_code == 200, res.text + return res.json()["actions"] + + +async def _reconcile_action(run_id: str) -> dict: + """这一条运行上「看差多少」那一项(按**搭建者**的账本读:普通使用者那一份视图里不出去口径的内部身份)。 + + 用例照它发起请求(workflow_id / version 是请求体要的;普通使用者那一份视图按 K14 只留人读的名字,见 ledger/view)。""" + async with SessionLocal() as session: + from app.ledger.view import run_view + + body = await run_view(run_id) + [action] = [a for a in body["actions"] if a["kind"] == "reconcile"] + return action + + +def _body(action: dict) -> dict: + return {"query": action["query"], "workflow_id": action["workflow_id"], "version": action["version"], + "inputs": CHECKED, "confirm": True} + + +async def _reconciled_runs(run_id: str) -> list[Run]: + async with SessionLocal() as session: + return await ledger_reconcile.reconciled_runs(session, run_id) + + +@contextlib.asynccontextmanager +async def _sandbox(): + """开登录的本地环境 + 一个普通使用者 uma:自己建的工作流、应用(授权)、运行退出时清掉,不给别的用例留授权。""" + from app.db.models_apps import App, AppGrant + from tests.fakes import auth_env + from tests.test_caliber_query_tool import grant_caliber + + made = {"workflows": [], "apps": []} + + async def publish(*, version: int = 1, workflow_id: str | None = None) -> str: + wf = await S.publish(version=version, workflow_id=workflow_id) + if wf not in made["workflows"]: + made["workflows"].append(wf) + return wf + + async def grant(workflow_id: str, version: int, who: str, role: str = "use") -> str: + app_id = await grant_caliber(workflow_id, version, who, role) + made["apps"].append(app_id) + return app_id + + async def revoke(app_id: str) -> None: + async with SessionLocal() as session: + await session.execute(delete(AppGrant).where(AppGrant.app_id == app_id)) + await session.commit() + + await auth_env.reset() + admin = await auth_env.turn_on_local() + await auth_env.make_user("uma", "user") + uma = await auth_env.login("uma") + started = utcnow() + try: + yield SimpleNamespace(publish=publish, grant=grant, revoke=revoke, uma=uma, admin=admin) + finally: + await uma.aclose() + await admin.aclose() + await auth_env.reset() + async with SessionLocal() as session: + # 只删这一次用例里它自己发起的运行(按开始的时刻划界),别去动别的用例留下的行 + await session.execute(delete(Run).where(Run.started_by == "uma", Run.created_at >= started)) + for app_id in made["apps"]: + await session.execute(delete(App).where(App.id == app_id)) + for wf_id in made["workflows"]: + await session.execute(delete(WorkflowVersion).where(WorkflowVersion.workflow_id == wf_id)) + await session.execute(delete(Workflow).where(Workflow.id == wf_id)) + await session.commit() + + +async def test_an_authorized_user_reconciles_and_reads_it_back(monkeypatch): + """有这一版的授权:对账照常发起(运行记在使用者名下),对过的账、那条运行照读。""" + async with _sandbox() as box: + wf = await box.publish() + await box.grant(wf, 1, "uma", "use") + row = await _answer_by(monkeypatch, "uma") + action = await _reconcile_action(row.id) + res = await box.uma.post(f"/api/ledger/answers/{row.id}/reconcile", json=_body(action)) + assert res.status_code == 201, res.text + done = await S.wait(res.json()["run_id"]) + assert done.status == "succeeded", done.error + assert done.started_by == "uma" and done.origin["source_run"] == row.id + assert done.origin["caliber"] == f"{wf}@1" + # 只读地看历史:账本视图里列着这一次对账,它自己那条运行也读得到 + view = (await box.uma.get(f"/api/runs/{row.id}/ledger")).json() + assert [r["run_id"] for r in view["reconciled"]] == [done.id] + assert (await box.uma.get(f"/api/runs/{done.id}/ledger")).status_code == 200 + + +async def test_a_version_without_the_grant_starts_no_run(monkeypatch): + """授权换到了新版(v2),对账要执行的是旧版(v1):发起前 403 querycore_not_authorized,一条运行都不起;历史照读。""" + async with _sandbox() as box: + wf = await box.publish() + first = await box.grant(wf, 1, "uma", "use") + row = await _answer_by(monkeypatch, "uma") + action = await _reconcile_action(row.id) + before = await box.uma.post(f"/api/ledger/answers/{row.id}/reconcile", json=_body(action)) + assert before.status_code == 201, before.text + done = await S.wait(before.json()["run_id"]) + + # 授权换到新版:v1 那份撤掉,另给一份 v2 的(对账要执行的还是记在这次运行里的 v1) + await box.revoke(first) + await box.publish(version=2, workflow_id=wf) + await box.grant(wf, 2, "uma", "use") + + res = await box.uma.post(f"/api/ledger/answers/{row.id}/reconcile", json=_body(action)) + assert res.status_code == 403 and res.json()["code"] == "querycore_not_authorized", res.text + assert res.json()["problems"] == [{"code": "querycore_not_authorized", "workflow_id": wf, "version": 1, + "role": ""}] + assert [r.id for r in await _reconciled_runs(row.id)] == [done.id], "一条新的对账运行都不该起" + + # 只读地看历史不受影响:账本视图、之前对过的账、那次对账运行的账本与证据照读 + assert (await box.uma.get(f"/api/runs/{row.id}/ledger")).status_code == 200 + assert (await box.uma.get(f"/api/runs/{done.id}/ledger")).status_code == 200 + assert (await box.uma.get(f"/api/runs/{done.id}/evidence")).status_code == 200 + + +async def test_any_unauthorized_version_of_the_batch_is_refused(): + """一次要执行好几版(召回那样新旧两版一起跑)时:缺任何一版都拒,problems 里逐条点出缺的是哪一版。""" + from app.api.coded import CodedHTTPException + from app.api.deps import Principal + from app.api.ledger import ensure_caliber_use + + async with _sandbox() as box: + wf = await box.publish() + await box.publish(version=2, workflow_id=wf) + await box.grant(wf, 1, "uma", "use") + async with SessionLocal() as session: + await ensure_caliber_use(session, "uma", [(wf, 1)], what="只执行授权过的那一版") + with pytest.raises(CodedHTTPException) as caught: + await ensure_caliber_use(session, "uma", [(wf, 2), (wf, 1)], what="口径召回") + assert caught.value.status_code == 403 and caught.value.code == "querycore_not_authorized" + assert caught.value.extra["problems"] == [{"code": "querycore_not_authorized", "workflow_id": wf, + "version": 2, "role": ""}] + # builder / admin:不按资产授权收窄 + for who in (Principal(username="uma", role="builder", verified=True, mode="local"), + Principal(username="uma", role="admin", verified=True, mode="local")): + await ensure_caliber_use(session, who, [(wf, 1), (wf, 2)], what="搭建者及以上") + # 两版都授权了:混着也不拒 + await box.grant(wf, 2, "uma", "use") + await ensure_caliber_use(session, "uma", [(wf, 1), (wf, 2)], what="口径召回") + # 关登录(这一档整条判定直接放行,不看资产授权) + async with SessionLocal() as session: + await ensure_caliber_use(session, None, [(wf, 1), (wf, 2)], what="关登录") + + +async def test_the_action_is_available_only_when_the_current_user_may_run_it(monkeypatch): + """`available` 按同一份资产授权标(caliber_role ≥ use;builder / admin / 关登录显式放行): + + - 使用者还没授权时那一项不可用,它在**它的**账本里也不带请求要用的 workflow_id / version——发不出去; + - 授权给它之后同一项变成可用,身份随之下发,照它发的请求真的对上; + - 搭建者那一档不受这一层收窄,同一项照样可用、带身份。""" + async with _sandbox() as box: + wf = await box.publish() + row = await _answer_by(monkeypatch, "uma") + + [before] = [a for a in await _actions(box.uma, row.id) if a["kind"] == "reconcile"] + assert before["available"] is False + assert "workflow_id" not in before and "version" not in before, "不可用的动作不带请求要用的身份" + assert before["caliber"] and before["query"], "人读的那一套(口径名、这条查询)照旧留着" + + await box.grant(wf, 1, "uma", "use") + [after] = [a for a in await _actions(box.uma, row.id) if a["kind"] == "reconcile"] + assert after["available"] is True + assert (after["workflow_id"], after["version"]) == (wf, 1) + res = await box.uma.post(f"/api/ledger/answers/{row.id}/reconcile", json=_body(after)) + assert res.status_code == 201, res.text + assert (await S.wait(res.json()["run_id"])).status == "succeeded" + + [builder] = [a for a in await _actions(box.admin, row.id) if a["kind"] == "reconcile"] + assert builder["available"] is True and builder["workflow_id"] == wf, "搭建者不看资产授权" + + +def _frontend_reconcile_body() -> tuple[set[str], set[str]]: + """前端 `LedgerReconcileIn`(frontend/src/typesLedger.ts)的(必填字段, 可选字段):服务端下发的动作要能拼出它。 + + 身份(`workflow_id` / `version`)在账本投影里只随 `available` 下发,前端把它们写成可选也是对的——所以这里两个集合 + 都要看。""" + text = (Path(__file__).resolve().parents[2] / "frontend" / "src" / "typesLedger.ts").read_text(encoding="utf-8") + block = text.split("export interface LedgerReconcileIn {", 1)[1].split("}", 1)[0] + required: set[str] = set() + optional: set[str] = set() + for line in block.splitlines(): + piece = line.strip().rstrip(",") + if not piece or ":" not in piece: + continue + name = piece.split(":", 1)[0].strip() + (optional if name.endswith("?") else required).add(name.rstrip("?")) + return required, optional + + +async def test_the_frontend_contract_holds_for_available_and_unavailable_actions(monkeypatch): + """前端契约:**可用**的那一项带齐前端发起请求要的字段(这条查询 + 那一版口径的身份),**不可用**的那一项不带身份。 + + 两者形状同一份,差别只在 `available`——账本投影就是按它决定留不留身份(无权的那几项只是说明,发不出去)。""" + async with _sandbox() as box: + wf = await box.publish() + app = await box.grant(wf, 1, "uma", "use") + row = await _answer_by(monkeypatch, "uma") + required, optional = _frontend_reconcile_body() + # 请求体要点名三样:这条查询(必填)+ 那一版口径的身份(可以写成可选) + assert "query" in required, f"前端契约变了:必填 {required}" + assert {"workflow_id", "version"} <= (required | optional), f"前端不再带口径身份:{required | optional}" + + [ok] = [a for a in await _actions(box.uma, row.id) if a["kind"] == "reconcile"] + assert ok["available"] is True + assert required <= set(ok) and {"workflow_id", "version"} <= set(ok), \ + f"可用动作缺前端要的字段:{(required | {'workflow_id', 'version'}) - set(ok)}" + + await box.revoke(app) + [no] = [a for a in await _actions(box.uma, row.id) if a["kind"] == "reconcile"] + assert no["available"] is False + missing = (required | {"workflow_id", "version"}) - set(no) + assert missing == {"workflow_id", "version"}, f"不可用动作只该少掉口径身份,别的照旧:{missing}" diff --git a/backend/tests/test_ledger_trial.py b/backend/tests/test_ledger_trial.py index aa4b15cf..342ae2c6 100644 --- a/backend/tests/test_ledger_trial.py +++ b/backend/tests/test_ledger_trial.py @@ -66,6 +66,106 @@ async def test_trial_refuses_missing_required_inputs_and_unknown_fields(client): assert unknown.status_code == 422 and "nope" in unknown.text +@pytest.fixture +def executed(monkeypatch) -> list[str]: + """这一次测试里真正发给数据库的语句(数据源适配器内联渲染之后的那一条),按先后。""" + from app.tools import datasource + + seen: list[str] = [] + real = datasource.run_query + + async def spy(source, sql, **kw): + seen.append(sql) + return await real(source, sql, **kw) + + monkeypatch.setattr(datasource, "run_query", spy) + return seen + + +async def trial_runs() -> list[str]: + """这次运行记录里由试跑发起的那些(别的来源不算),按运行 id。""" + from sqlalchemy import select + + async with SessionLocal() as session: + runs = (await session.execute(select(Run))).scalars().all() + return [r.id for r in runs if (r.origin or {}).get("kind") == "caliber_trial"] + + +async def test_trial_refuses_an_incomplete_parameter_before_any_sql(client, executed): + """可选、没有缺省值的参数这次没给:试跑在**发起运行之前**回结构化 422,一条 SQL 都不发(K01)。""" + sql = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' AND region = '{{ input.store }}' " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") + graph = S.caliber_graph(sql=sql) + graph["nodes"][0]["data"]["config"]["fields"] = [{"name": "start", "required": True}, + {"name": "end", "required": True}, + {"name": "store"}] + wf = await S.publish(graph=graph) + before = await trial_runs() + res = await client.post(f"/api/ledger/calibers/{wf}/1/card/trial", + json={"inputs": {"start": "2026-09-01", "end": "2026-09-08"}}) + assert res.status_code == 422, res.text + body = res.json() + assert body["code"] == "missing_parameter" and "store" in body["detail"] + assert "不能当空串用" in body["detail"] + [problem] = body["problems"] + assert (problem["code"], problem["name"], problem["node_id"]) == ("missing_parameter", "store", "fetch") + assert executed == [] and await trial_runs() == before + + +async def test_trial_reports_an_undeclared_parameter_as_a_structured_422(client, executed): + """取数模板引用了入口没声明的字段:结构化 422(undeclared_parameter),连逐条由于 problems 一起交回,不发 SQL、不起运行。""" + wf = await S.publish(graph=S.caliber_graph( + sql="SELECT SUM(amount) AS gmv FROM orders WHERE region = '{{ input.nope }}'")) + before = await trial_runs() + res = await client.post(f"/api/ledger/calibers/{wf}/1/card/trial", + json={"inputs": {"start": "2026-09-01", "end": "2026-09-08"}}) + assert res.status_code == 422, res.text + body = res.json() + assert body["code"] == "undeclared_parameter" and "nope" in body["detail"] + [problem] = body["problems"] + assert (problem["code"], problem["name"], problem["node_id"]) == ("undeclared_parameter", "nope", "fetch") + assert executed == [] and await trial_runs() == before + + +async def test_trial_treats_an_explicit_empty_string_as_missing_not_empty(client, executed): + """显式传空串、字段又没有缺省值:按缺参数拒(结构化 422),不拿空串去发 SQL。 + + 空串不是值,是省略——这条和组合式问数同一套(ledger/params.provided);声明了 `default=""` 的字段照声明走(见下一条)。""" + sql = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' AND region = '{{ input.store }}' " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") + graph = S.caliber_graph(sql=sql) + graph["nodes"][0]["data"]["config"]["fields"] = [{"name": "start", "required": True}, + {"name": "end", "required": True}, + {"name": "store"}] + wf = await S.publish(graph=graph) + before = await trial_runs() + res = await client.post(f"/api/ledger/calibers/{wf}/1/card/trial", + json={"inputs": {"start": "2026-09-01", "end": "2026-09-08", "store": ""}}) + assert res.status_code == 422, res.text + body = res.json() + assert body["code"] == "missing_parameter" and "store" in body["detail"] + assert executed == [] and await trial_runs() == before + + +async def test_trial_keeps_the_authors_declared_empty_default(client, executed): + """作者声明了 `default=""` 的可选参数(模板里写成「空值不过滤」):照声明当空串跑,不算缺参数。""" + sql = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' " + "AND ('{{ input.store }}' = '' OR region = '{{ input.store }}') " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") + graph = S.caliber_graph(sql=sql) + graph["nodes"][0]["data"]["config"]["fields"] = [{"name": "start", "required": True}, + {"name": "end", "required": True}, + {"name": "store", "default": ""}] + wf = await S.publish(graph=graph) + res = await client.post(f"/api/ledger/calibers/{wf}/1/card/trial", + json={"inputs": {"start": "2026-09-01", "end": "2026-09-08"}}) + assert res.status_code == 200, res.text + assert res.json()["status"] == "succeeded", res.json() + # 参数渲染进去了(不是原样带着 {{ }} 发出去):声明成空串的那一处就是 '',日期照常 + [sql] = executed + assert "{{" not in sql and "('' = '' OR region = '')" in sql and "'2026-09-01'" in sql + + async def test_trial_queries_mask_the_configured_columns_and_never_return_sql(client): """试跑结果集把数据源设了遮罩的列换成「已遮罩」(改了名字的结果列也认);响应里不出现 SQL,SQL 里可能写着遮罩值。""" from sqlalchemy import select diff --git a/backend/tests/test_merge_node.py b/backend/tests/test_merge_node.py index a2fde5d5..5c87b11f 100644 --- a/backend/tests/test_merge_node.py +++ b/backend/tests/test_merge_node.py @@ -294,6 +294,44 @@ def test_labels_and_governance_know_the_type(): # -------------------------------------------------------------------------- +#: 服务端按维度值拼好的对齐语句(ledger/reconcile.align_sql):值来自查询结果,可能就是带 {{ }} 的文本 +LITERAL_MERGE_SQL = ("SELECT s.日期, s.门店, s.订单数, s.销售额, v.到店人数, '{{ vars.region }}' AS 备注 " + "FROM s JOIN v ON s.日期 = v.日期 AND s.门店 = v.门店 ORDER BY s.日期, s.门店") + + +async def test_a_server_built_merge_statement_is_not_templated_again(monkeypatch, sources): + """服务端拼好的合并语句(带参数契约,哈希对得上):里面的 {{ }} 是数据,运行时不再渲染一遍。 + + 对账图里按维度值对齐的那条语句由服务端拼成字面 SQL,维度值直接来自查询结果。真被当模板渲染一遍,这里那句 + `'{{ vars.region }}'` 会被换成空串(图里根本没有这个变量),合并执行的就不再是服务端拼的那条语句了(K01 的二次渲染)。""" + from app.ledger import params + + graph = store_graph(merge_sql=LITERAL_MERGE_SQL, report=False) + merge = next(n for n in graph["nodes"] if n["id"] == "merge")["data"]["config"] + merge[params.KEY] = params.marker(rendered=merge["sql"], source={"kind": "reconcile", "node_id": "merge"}) + assert params.literal_keys(merge, "merge") == ("sql",) + row = await run_graph(monkeypatch, graph) + assert row.status == "succeeded", row.error + [done] = await events(row.id, "merge.end", "merge") + assert "'{{ vars.region }}'" in done["sql"] and done["rows"] == 4 + + +async def test_editing_the_merge_sql_after_a_copy_drops_the_contract(monkeypatch, sources): + """复制一个服务端拼好的合并节点、改过它的 SQL:契约作废,按普通模板走——带 {{ }} 的语句不会被原样发出去。 + + 改过之后图里的变量校验恢复了(`{{ vars.region }}` 没人产出 → 运行发起前就拦下),一条 SQL 都不发。""" + from app.ledger import params + + graph = store_graph(merge_sql=LITERAL_MERGE_SQL, report=False) + merge = next(n for n in graph["nodes"] if n["id"] == "merge")["data"]["config"] + merge[params.KEY] = params.marker(rendered=merge["sql"], source={"kind": "reconcile", "node_id": "merge"}) + merge["sql"] = merge["sql"].replace("ORDER BY", "-- 复制过来改了 --\nORDER BY") + assert params.literal_keys(merge, "merge") == () + with pytest.raises(ValueError) as caught: + await run_manager.start(graph=graph, input_payload={}) + assert "vars.region" in str(caught.value) and "没有任何节点产出" in str(caught.value) + + async def test_end_to_end_two_databases(monkeypatch, sources, client): row = await run_graph(monkeypatch) assert row.status == "succeeded", row.error diff --git a/backend/tests/test_metric_id_duplicate.py b/backend/tests/test_metric_id_duplicate.py new file mode 100644 index 00000000..731786f6 --- /dev/null +++ b/backend/tests/test_metric_id_duplicate.py @@ -0,0 +1,174 @@ +"""指标 ID 收口:同一张口径卡上的指标 ID 要唯一(K08 的重复身份)。 + +下游 `nodes.<卡>.metrics[i]`、出具契约、比例契约、报告引用都按指标 ID 与位置取数:同一张卡上两个指标同名就分不清是哪一条。 +所以**画布 / 发布前检查**(engine/schema)和**运行时**(engine/nodes/metrics)都要拦住,不能取第一条静默执行——那会把另一条的 +数顶替过来。闭合解析(ledger/closure.selection_index)遇到同名只留第一次,运行时不能顺着它把第一条算出来,必须在过滤前 +就响亮失败(两边都不静默,不冲突)。 + +空 ID(没写声明的)不算重复:缺 ID 另有报法(画布 metrics.id_missing、运行时「指标定义不完整」)。旧正常图(ID 唯一) +行为一字不变。数据是虚构店铺库。 +""" +from __future__ import annotations + +import pytest + +from app.engine.nodes.metrics import SelectionRefused, duplicate_metric_ids, require_selection +from app.engine.runner import run_manager +from app.engine.schema import GraphSpec, validate_graph +from tests import ledger_samples as S + +INPUTS = {"start": "2026-09-01", "end": "2026-09-08"} + + +@pytest.fixture(autouse=True) +async def engine_up(tmp_path): + await run_manager.setup() + await S.fresh_source(tmp_path / "shop.db") + yield + await run_manager.shutdown() + + +# ========================================================================== +# 纯函数:重复的认定 +# ========================================================================== + + +def test_duplicate_metric_ids_ignores_blank_and_reports_each_id_once(): + defs = [{"id": "a"}, {"id": "b"}, {"id": "a"}, {"id": " a "}, {"id": ""}, {"x": 1}, {"id": "b"}, {"id": "b"}] + assert duplicate_metric_ids(defs) == ["a", "b"] + # 空 ID / 不是字典 / 没有 id 的都不算重复(另有报法) + assert duplicate_metric_ids([{"id": ""}, {"id": " "}, {"x": 1}, {}, "nope"]) == [] + assert duplicate_metric_ids([]) == [] + + +def test_require_selection_refuses_duplicates_instead_of_taking_the_first(): + """闭合解析对同名只留第一次;运行时不能顺着它算第一条——要在过滤前就响亮失败。""" + defs = [{"id": "gmv", "expression": "cell(nodes.fetch, 0, 'gmv')"}, + {"id": "gmv", "expression": "cell(nodes.fetch, 0, 'other')"}] + with pytest.raises(SelectionRefused, match="重复"): + require_selection(defs, ["gmv"]) + + +def test_closure_and_runtime_share_the_duplicate_verdict(): + """闭包把重复记成未决、运行时响亮失败:判定只有一处(ledger.closure.duplicate_metric_ids),不冲突。""" + from app.ledger import closure + + graph = S.chain(S.node("start", "input"), + S.node("fetch", "tool", tool=S.tool(), args={"sql": S.TEMPLATE}), + S.node("card", "metrics", metrics=[{"id": "gmv", "expression": "cell(nodes.fetch, 0, 'gmv')"}, + {"id": "gmv", "expression": "cell(nodes.fetch, 0, 'other')"}])) + metrics = graph["nodes"][2]["data"]["config"]["metrics"] + assert closure.DUPLICATE_METRIC_ID in closure.CODES + assert closure.duplicate_metric_ids(metrics) == duplicate_metric_ids(metrics) == ["gmv"] + # 闭包:这张卡本身未决;运行时:过滤前就拒(绝不取第一条) + assert closure.DUPLICATE_METRIC_ID in [p["code"] for p in closure.build(graph, "wf-dup", 1, "card").unresolved] + with pytest.raises(SelectionRefused, match="重复"): + require_selection(metrics, ["gmv"]) + + +# ========================================================================== +# 画布 / 发布前检查:schema 报错 +# ========================================================================== + + +def duplicate_card(*, with_caliber_from: bool = False) -> dict: + metrics = [{"id": "gmv", "name": "销售额", "unit": "元", "expression": "cell(nodes.fetch, 0, 'gmv')"}, + {"id": "gmv", "name": "销售额(重复)", "unit": "元", + "expression": "cell(nodes.fetch, 0, 'gmv')"}] + card_config: dict = {"metrics": metrics} + if with_caliber_from: + card_config["caliber_from"] = {"workflow_id": "wf", "workflow_version": 1, "node_id": "card"} + return S.chain(S.node("start", "input", fields=[{"name": "start", "required": True}, {"name": "end", "required": True}]), + S.node("fetch", "tool", tool=S.tool(), args={"sql": S.TEMPLATE}), + S.node("card", "metrics", caliber="重复口径", caliber_version="v1", **card_config), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.card.text }}"}])) + + +def issues(graph: dict) -> list: + return list(validate_graph(GraphSpec.model_validate(graph)).issues) + + +def test_schema_rejects_a_duplicate_metric_id(): + found = [i for i in issues(duplicate_card()) if i.code == "metrics.id_duplicate"] + assert found and [i.level for i in found] == ["error"] + assert found[0].node_id == "card" and "gmv" in found[0].message + assert any("唯一" in i.message for i in found) + + +def test_schema_flags_duplicates_even_on_a_caliber_from_card(): + """转抄卡本地写的 metrics 不生效,但同一张卡上的 ID 照样要唯一(现状是给一条「不会生效」的警告)。""" + found = [i for i in issues(duplicate_card(with_caliber_from=True)) if i.code == "metrics.id_duplicate"] + assert found + + +def test_schema_leaves_unique_ids_and_blank_ids_alone(): + unique = S.chain(S.node("start", "input"), S.node("fetch", "tool", tool=S.tool(), args={"sql": S.TEMPLATE}), + S.node("card", "metrics", metrics=[ + {"id": "a", "name": "A", "expression": "cell(nodes.fetch, 0, 'gmv')"}, + {"id": "b", "name": "B", "expression": "cell(nodes.fetch, 0, 'gmv')"}])) + assert not [i for i in issues(unique) if i.code == "metrics.id_duplicate"] + # 两条都没有 ID:是「缺少 ID」,不是「重复」 + blank = S.chain(S.node("start", "input"), S.node("fetch", "tool", tool=S.tool(), args={"sql": S.TEMPLATE}), + S.node("card", "metrics", metrics=[ + {"id": "", "name": "A", "expression": "cell(nodes.fetch, 0, 'gmv')"}, + {"name": "B", "expression": "cell(nodes.fetch, 0, 'gmv')"}])) + codes = [i.code for i in issues(blank)] + assert "metrics.id_missing" in codes and "metrics.id_duplicate" not in codes + + +# ========================================================================== +# 运行时:源卡读取(本地卡 / 转抄卡)也响亮失败 +# ========================================================================== + + +async def run(graph: dict): + started = await run_manager.start(graph=graph, input_payload=dict(INPUTS)) + return await S.wait(started.id) + + +async def upstream_with_duplicates() -> str: + graph = S.chain( + S.node("start", "input", fields=[{"name": "start", "required": True}, {"name": "end", "required": True}]), + S.node("fetch", "tool", tool=S.tool(), args={"sql": S.TEMPLATE}), + S.node("card", "metrics", caliber="重复口径", caliber_version="v1", metrics=[ + {"id": "gmv", "name": "销售额", "unit": "元", "expression": "cell(nodes.fetch, 0, 'gmv')"}, + {"id": "gmv", "name": "销售额(重复)", "unit": "元", "expression": "cell(nodes.fetch, 0, 'gmv')"}])) + return await S.publish(graph=graph, name="K08 重复上游") + + +def consumer(workflow_id: str, *, selection: list[str] | None = None) -> dict: + ref: dict = {"workflow_id": workflow_id, "workflow_version": 1, "node_id": "card"} + if selection is not None: + ref["metrics"] = list(selection) + return S.chain( + S.node("start", "input", fields=[{"name": "start", "required": True}, {"name": "end", "required": True}]), + S.node("fetch", "tool", tool=S.tool(), args={"sql": S.TEMPLATE}), + S.node("card", "metrics", caliber_from=ref), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.card.text }}"}])) + + +async def test_runtime_refuses_duplicate_ids_on_a_pinned_card(): + """钉住的那一版卡上 ID 重复:整卡读取也要响亮失败,不能取第一条静默执行。""" + workflow_id = await upstream_with_duplicates() + row = await run(consumer(workflow_id)) + assert row.status == "failed" and "重复" in str(row.error) + assert "gmv" in str(row.error) + + +async def test_runtime_refuses_a_selection_over_a_duplicate_card(): + """带选择点名那个重复的 ID:闭合解析只留第一次,运行时不能顺着它算第一条——在过滤前就拦住。""" + workflow_id = await upstream_with_duplicates() + row = await run(consumer(workflow_id, selection=["gmv"])) + assert row.status == "failed" and "重复" in str(row.error) + assert "gmv" in str(row.error) + + +async def test_runtime_leaves_a_unique_card_alone(): + row = await run(consumer(await S.publish(name="K08 唯一上游"))) + assert row.status == "succeeded", row.error + + +async def test_publish_precheck_blocks_a_duplicate_local_card(): + """本地重复 ID 的卡过不了画布 / 发布前检查:run_manager.start 直接拒,不会跑到运行时。""" + with pytest.raises(ValueError, match="重复"): + await run_manager.start(graph=duplicate_card(), input_payload=dict(INPUTS)) diff --git a/backend/tests/test_publication_gate.py b/backend/tests/test_publication_gate.py new file mode 100644 index 00000000..f57a0297 --- /dev/null +++ b/backend/tests/test_publication_gate.py @@ -0,0 +1,964 @@ +"""K07 的用途判定:requires_proof、正式身份、探索不受限(任务书 4.9,E10/E15)。 + +这份文件盯住这几条: + +1. **正式身份只有一个入口。** 正式运行(engine/launch.launch_run)和按口径出具(ledger/issue.check_target)在 + requires_proof 时,必须有一份**就是这一版这一张图的**(图指纹对得上、图上的源头口径卡一张不缺)、覆盖当前 + 定义 + 绑定 + 取数语义、最新的那条验证记录是 matched、且认证确认盖住这份记录全部指标**的发布依据;部分审阅不行, + 缺记录/旧记录不覆盖/错图/缺卡各有机器码,别的入口绕不过去。两条入口对同一份依据不足给的机器码和身份完全一致。 + **转抄卡(caliber_from)固定引用的上游那张卡按同一个用途递归判**:上游要证明就得同样满足,失败按上游那条机器码 + 加下游引用拒;只判被引用那张卡、循环引用截断、上游是老资产的不升级。 +2. **requires_proof = 发布时要求过证明(事件行上的 required)或现在还接管着**(apps/versions.taken_over),两者取或; + 引用的上游要证明也算。清标签不能让已经按严格发的那些版本降级,普通 PATCH 也清不掉接管标记。老资产(这一版没有 + 清单)保持原行为,只是身份记 formal_legacy;不需要证明的记 formal_unproven——**都不是 verified**。 +3. **试算、探索、组合不因缺验证审阅被误伤**(A03/A07):purpose 由服务端入口常量决定,只有正式运行和出具会拦。 +4. **运行来源/日志保留实际清单、版本和身份**(要求 5);来源里的 explicit 照实记调用方有没有点名版本——默认发起 + (不传 version)是 false,只按推荐指针取一次并固定。 +5. **删掉没验证过的语义字段不会把旧依据升成通过**(E15/R07)。 +6. **依据只能在发布那一刻定下来。** 发布之后补的验证记录/审阅不会把这一版的依据补成通过(不在核对发布事件时另挑 + 更新的记录),清单里没有的卡也不会现场挑一条记录顶上;图里每张源头口径卡各要一份自己的依据,一张齐了不算另一张 + 也齐;之后又试运行过一次、那一次不是 matched 的,说明最新一次核对的结论就不是「对得上」,不拿更早那条顶上。 + +数据是虚构店铺库(tests/ledger_samples),跑的是真实入口;正式运行在假模型下跑完,不连真实业务库。 +""" +from __future__ import annotations + +import pytest +from httpx import ASGITransport, AsyncClient +from sqlalchemy import select + +from app.apps import publications +from app.db.base import SessionLocal +from app.core import artifact_store +from app.db.models import Run, RunEvent, Workflow +from app.engine.runner import run_manager +from app.ledger import validation +from app.main import app +from tests import ledger_samples as S +from tests.publication_samples import (CARD, add_record, add_version, confirm, launch_formal, latest_event, + issue_plan, make_workflow, persisted, publication_of, publish, report_model, wait_run) + +@pytest.fixture(autouse=True) +async def engine_up(tmp_path): + await run_manager.setup() + await S.fresh_source(tmp_path / "shop.db") + yield + await run_manager.shutdown() + + +@pytest.fixture +async def client(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c: + yield c + + +def principal(role: str = "builder"): + from app.api.deps import Principal + + return Principal(username="boss", role=role, mode="off", via="off") + + +def two_metric_graph(): + """同一张卡上两条指标(都读 fetch 的 gmv 列):用来演「只确认了一部分」。""" + graph = S.caliber_graph() + card = next(node for node in graph["nodes"] if node["id"] == CARD) + card["data"]["config"]["metrics"].append( + {"id": "orders", "name": "订单数", "unit": "单", "expression": "cell(nodes.fetch, 0, 'gmv') * 2"}) + return graph + + +def two_card_graph(): + """同一张取数上两张源头口径卡:用来演「只证明了其中一张,另一张不能跟着算过」。""" + graph = S.caliber_graph() + graph["nodes"].insert(3, S.node("card2", "metrics", caliber="退款额", caliber_version="v1", + metrics=[{"id": "refunds", "name": "退款额", + "expression": "cell(nodes.fetch, 0, 'gmv')"}])) + return graph + + +def graph_without_definition(): + """同一张卡、只把「没验证过的那段业务描述」删掉(语义字段变了,定义指纹跟着变)。""" + graph = S.caliber_graph() + card = next(node for node in graph["nodes"] if node["id"] == CARD) + card["data"]["config"]["metrics"][0].pop("definition", None) + return graph + + +def graph_with_definition(): + graph = S.caliber_graph() + card = next(node for node in graph["nodes"] if node["id"] == CARD) + card["data"]["config"]["metrics"][0]["definition"] = {"text": "只算已支付订单的销售额", "exclusions": ["退款"]} + return graph + + +# -------------------------------------------------------------------------- +# 1、正式运行:依据齐全才发得起来,身份与清单记在来源和日志里 +# -------------------------------------------------------------------------- + + +async def test_a_proven_asset_pins_its_manifest_identity_and_log(client, monkeypatch): + report_model(monkeypatch) + asset = await make_workflow() + record_id = await add_record(asset) + await confirm(asset, record_id) + out = await publish(client, asset) + run = await launch_formal(asset) + assert run.version == 1 + info = publication_of(run) + assert info["manifest"] == out["manifest"] and info["version"] == 1 + assert info["identity"] == publications.PROVEN and info["requires_proof"] is True + assert info["publication"] and info["purpose"] == publications.PURPOSE_FORMAL + done = await wait_run(run.id) + assert done.status == "succeeded", done.error + # 事件流里也有一条:回看这次运行能对上是哪一份清单 + async with SessionLocal() as session: + events = (await session.execute(select(RunEvent).where(RunEvent.run_id == run.id))).scalars().all() + [pinned] = [e for e in events if isinstance(e.data, dict) and e.data.get("code") == "publication.pinned"] + assert pinned.data["manifest"] == out["manifest"] and pinned.data["identity"] == publications.PROVEN + assert pinned.data["version"] == 1 and "发布依据齐全" in pinned.data["message"] + # 运行来源里也记着(run.origin 事件) + [origin_event] = [e for e in events if e.type == "run.origin"] + assert origin_event.data["publication"]["manifest"] == out["manifest"] + + +@pytest.mark.parametrize("missing", ["record", "unmatched", "review", "rejected", "partial"]) +async def test_formal_run_and_issue_are_refused_with_the_same_code(client, missing): + """缺记录 / 不是 matched / 没有审阅 / 被驳回 / 只确认了一部分:两条入口逐个明确拒,机器码和身份一致。""" + from app.engine.launch import LaunchRefused + from app.ledger import issue as ledger_issue + + asset = await make_workflow(graph=two_metric_graph()) + if missing != "record": + metric_ids = ("gmv", "orders") + record_id = await add_record(asset, status="observed" if missing == "unmatched" else "matched", + metric_ids=metric_ids) + if missing == "rejected": + await confirm(asset, record_id, decision="rejected", scope=list(metric_ids)) + elif missing == "partial": + await confirm(asset, record_id, scope=["gmv"]) + elif missing == "unmatched": + await confirm(asset, record_id, scope=list(metric_ids)) + # missing == "review":有记录、没有审阅 + await publish(client, asset) + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + expected = {"record": publications.RECORD_MISSING, "unmatched": publications.RECORD_NOT_MATCHED, + "review": publications.REVIEW_MISSING, "rejected": publications.REVIEW_REJECTED, + "partial": publications.REVIEW_PARTIAL}[missing] + assert caught.value.code == expected, caught.value + assert "发布依据" in caught.value.message + # 按口径出具走的是同一套判定:机器码、身份、要求证明这三样一模一样(出具这条路没有另一套说法) + async with SessionLocal() as session: + plan = await issue_plan(session, asset) + assert plan.code == expected and plan.publication["identity"] == publications.UNPROVEN + assert plan.publication["requires_proof"] is True and plan.publication["manifest"] + assert "发布依据" in plan.reason + + +async def test_an_unauthenticated_review_is_refused_when_login_is_on(client, monkeypatch): + """开着登录的部署里,审阅必须是认证主体做的(K05 记的 verified)——自报署名不算正式依据。""" + from app import auth + from app.engine.launch import LaunchRefused + + asset = await make_workflow(graph=two_metric_graph()) + record_id = await add_record(asset, metric_ids=("gmv", "orders")) + await confirm(asset, record_id, verified=False, scope=["gmv", "orders"]) + await publish(client, asset) + monkeypatch.setattr("app.auth.current_mode", lambda: "local") + assert auth.current_mode() == "local" + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == publications.REVIEW_UNVERIFIED + monkeypatch.undo() + # 认证过的审阅照常放行 + record2 = await add_record(asset, metric_ids=("gmv", "orders"), status="matched") + await confirm(asset, record2, verified=True, scope=["gmv", "orders"]) + await publish(client, asset) + assert publication_of(await launch_formal(asset))["identity"] == publications.PROVEN + + +async def test_a_record_that_no_longer_covers_the_version_is_refused(client): + """定义/取数改过之后,旧记录不算覆盖新版本:正式运行明确拒,不回退成「没要求证明」。""" + from app.engine.launch import LaunchRefused + + asset = await make_workflow() + record_id = await add_record(asset) + await confirm(asset, record_id) + await publish(client, asset) + asset = await add_version(asset, S.caliber_graph(S.TEMPLATE.replace("'paid'", "'open'")), version=2) + out = await publish(client, asset, version=2) + assert out["publication"]["problems"][0]["code"] == publications.RECORD_STALE + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset, version=2) + assert caught.value.code == publications.RECORD_STALE + # 老的 v1 仍然按它自己那份依据发起(清单是那一版的) + run = await launch_formal(asset, version=1) + assert publication_of(run)["identity"] == publications.PROVEN + + +async def test_the_http_entry_refuses_with_the_same_machine_code(client): + asset = await make_workflow() + await publish(client, asset) # 没有任何验证记录 + res = await client.post("/api/runs", json={"workflow_id": asset["workflow_id"], "run_class": "formal", + "version": 1, "input": {"start": "2026-09-01", + "end": "2026-09-08"}}) + assert res.status_code == 409 and res.json()["code"] == publications.RECORD_MISSING + assert "发布依据" in res.json()["detail"] + async with SessionLocal() as session: + assert (await session.execute(select(Run).where(Run.workflow_id == asset["workflow_id"]))).scalars().all() == [] + + +# -------------------------------------------------------------------------- +# 2、老资产与「不需要证明」的资产:保持原行为,但都不能被说成验证过了 +# -------------------------------------------------------------------------- + + +async def test_a_legacy_asset_keeps_its_behaviour_and_is_marked_legacy(client, monkeypatch): + """加发布清单这一机制之前发布的资产(这一版没有清单):正式运行照旧发得起来,身份记 formal_legacy。""" + report_model(monkeypatch) + workflow_id = await S.publish() # 直接写库(老写法,不经过发布入口) + async with SessionLocal() as session: + workflow = await session.get(Workflow, workflow_id) + workflow.tags = ["doc_draft"] # 已接管,但没有清单 + await session.commit() + run = await launch_formal({"workflow_id": workflow_id, "version": 1}) + info = publication_of(run) + assert info["identity"] == publications.LEGACY and info["requires_proof"] is False + assert info["manifest"] is None and info["publication"] is None + assert (await wait_run(run.id)).status == "succeeded" + + +async def test_an_asset_outside_the_proof_scope_is_unproven_not_verified(client, monkeypatch): + """不是「已接管」的资产(手建的画布工作流):这一版照样有清单,但不要求证明,身份是 formal_unproven。""" + report_model(monkeypatch) + asset = await make_workflow(tags=[]) + out = await publish(client, asset) + assert out["manifest"] and out["publication"]["required"] is False + run = await launch_formal(asset) + info = publication_of(run) + assert info["identity"] == publications.UNPROVEN and info["requires_proof"] is False + assert info["manifest"] == out["manifest"] + assert (await wait_run(run.id)).status == "succeeded" + + +# -------------------------------------------------------------------------- +# 3、试算、探索、组合不被这套门禁误伤 +# -------------------------------------------------------------------------- + + +async def test_explore_trial_and_compose_are_never_refused_for_missing_proof(client): + from app.look.calibers import CaliberKind + + asset = await make_workflow() + await publish(client, asset) # 有清单、没有验证记录、也没有审阅 + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + for purpose in (publications.PURPOSE_EXPLORE, publications.PURPOSE_TRIAL, + publications.PURPOSE_COMPOSE): + judged = await publications.judge(session, workflow, version=1, purpose=purpose) + assert judged.refusal is None, f"{purpose} 不该被发布依据拦" + assert judged.requires_proof is False + # 目录和组合式问数照常看得见这一版 + kind = await CaliberKind.load(session, compose=True) + items = [i for i in kind.items if i.workflow_id == workflow.id] + assert [i.version for i in items] == [1] + [option] = [o for o in kind.options or [] if o.workflow_id == workflow.id] + assert option.composable is True + # 画布上的探索运行照常发起(同一条 launch_run,run_class=exploratory) + from app.engine.launch import launch_run + + async with SessionLocal() as session: + exploratory = await launch_run(session, workflow_id=asset["workflow_id"], run_class="exploratory", + actor="试跑人", input_payload={"start": "2026-09-01", "end": "2026-09-08"}) + assert exploratory.run_class == "exploratory" + assert publication_of(exploratory) == {}, "探索运行不继承正式身份,也不固定发布依据" + assert (await wait_run(exploratory.id)).status in ("succeeded", "failed") + + +# -------------------------------------------------------------------------- +# 4、按口径出具:同一套判定,不能经另一条路拿到正式身份 +# -------------------------------------------------------------------------- + + +async def test_issue_is_refused_without_the_publication_basis(client): + from app.ledger import issue as ledger_issue + + asset = await make_workflow() + await publish(client, asset) # 没有验证记录 + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + plan = await issue_plan(session, asset) + assert plan.reason and plan.code == publications.RECORD_MISSING + assert "发布依据" in plan.reason + # 依据齐全之后(同一版重新发布),出具有了正式身份,缺的是别的东西(入口必填没值) + record_id = await add_record(asset) + await confirm(asset, record_id) + # 依据补上之后重新发布(同一个发布入口):这一版才有正式身份 + from app.api.workflows import commit_publish + + await commit_publish(session, workflow, await _version_row(session, asset), "published", "发布人") + plan = await issue_plan(session, asset) + assert plan.code not in (publications.RECORD_MISSING, publications.RECORD_STALE, publications.REVIEW_MISSING, + publications.REVIEW_PARTIAL) + assert plan.publication["identity"] == publications.PROVEN + + +async def _version_row(session, asset: dict): + from app.db.models import WorkflowVersion + + return (await session.execute(select(WorkflowVersion).where( + WorkflowVersion.workflow_id == asset["workflow_id"], + WorkflowVersion.version == asset["version"]))).scalar_one() + + +# -------------------------------------------------------------------------- +# 5、E15:删掉没验证过的语义字段不会把旧依据升成通过 +# -------------------------------------------------------------------------- + + +async def test_deleting_an_unverified_field_does_not_upgrade_the_basis(client): + """删掉一段业务描述就改了定义指纹:旧记录/旧审阅仍可追,但不再覆盖新版本——正式运行照样拒。""" + from app.engine.launch import LaunchRefused + + asset = await make_workflow(graph=graph_with_definition()) + record_id = await add_record(asset) + await confirm(asset, record_id) + await publish(client, asset) + run = await launch_formal(asset) + assert publication_of(run)["identity"] == publications.PROVEN + # 把那一段描述删掉(没验证过的那一项),存出新的一版并重新发布 + changed = graph_without_definition() + asset = await add_version(asset, changed, version=2) + out = await publish(client, asset, version=2) + assert out["publication"]["proven"] is False + assert out["publication"]["problems"][0]["code"] == publications.RECORD_STALE + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset, version=2) + assert caught.value.code == publications.RECORD_STALE + # 旧记录和旧审阅都还在库里、照旧可追,只是不算覆盖这一版 + async with SessionLocal() as session: + record = await validation.get_record(session, asset["draft_id"], record_id) + current = validation.materials(changed, CARD, workflow_id=asset["workflow_id"]) + assert record.status == "matched" and not validation.covers_current(record, current=current) + summary = validation.summarize([record], current=current) + assert summary["verdict"] == "stale" and summary["covers_current"] is False + # 那一版最后一次发布留下的清单里照实写着依据不齐 + event = await latest_event(asset["workflow_id"], 2) + assert event.proven is False and event.cards[0]["proof"]["code"] == publications.RECORD_STALE + + +# -------------------------------------------------------------------------- +# 6、依据只能在发布那一刻定下来:补的记录、别的卡、之后没过的那一次,都升不上去 +# -------------------------------------------------------------------------- + + +async def test_a_basis_is_never_upgraded_by_records_added_later(client, monkeypatch): + """发布时没有记录,之后补上记录和审阅:这一版的依据照旧不齐,要重新发布才算数(另挑更新的记录就是后门)。""" + from app.engine.launch import LaunchRefused + + report_model(monkeypatch) + asset = await make_workflow() + out = await publish(client, asset) + assert out["publication"]["proven"] is False + record_id = await add_record(asset) + await confirm(asset, record_id) + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.code == publications.RECORD_MISSING and judged.identity == publications.UNPROVEN + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == publications.RECORD_MISSING + # 重新发布(同一个入口)才把这一版重新按现在的记录认可一遍 + assert (await publish(client, asset))["publication"]["proven"] is True + run = await launch_formal(asset) + assert publication_of(run)["identity"] == publications.PROVEN + assert (await wait_run(run.id)).status == "succeeded" + + +async def test_every_source_card_needs_its_own_basis(client, monkeypatch): + """图里两张源头口径卡:证明了一张不算另一张也过了,缺的那张照样拦,补上之后重新发布才齐。""" + from app.engine.launch import LaunchRefused + + report_model(monkeypatch) + asset = await make_workflow(graph=two_card_graph()) + record_id = await add_record(asset) # 只覆盖 card + await confirm(asset, record_id) + out = await publish(client, asset) + assert out["publication"]["proven"] is False + assert [p["card_id"] for p in out["publication"]["problems"]] == ["card2"] + assert out["publication"]["problems"][0]["code"] == publications.RECORD_MISSING + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == publications.RECORD_MISSING + # 另一张卡也有了自己的 matched + 审阅,重新发布之后才整份齐 + other = await add_record(asset, card_id="card2", metric_ids=("refunds",)) + await confirm(asset, other, scope=["refunds"]) + assert (await publish(client, asset))["publication"]["proven"] is True + run = await launch_formal(asset) + assert publication_of(run)["identity"] == publications.PROVEN + assert (await wait_run(run.id)).status == "succeeded" + + +@pytest.mark.parametrize("later", ["mismatched", "observed"]) +async def test_a_later_trial_that_is_not_matched_takes_the_basis_away(client, later): + """先有一条 matched + 审阅,之后又跑了一次没过(同一份定义):已发布那一版的依据是发布那一刻定下的,照旧; + **重新发布**时按最新的那条重算——不拿更早那条顶上(K05 的卡级结论按的也是最新那条)。""" + from app.engine.launch import LaunchRefused + + asset = await make_workflow() + record_id = await add_record(asset) + await confirm(asset, record_id) + assert (await publish(client, asset))["publication"]["proven"] is True + await add_record(asset, status=later) # 同一份定义、更新的一条 + # 已经发布的那一份依据不被后来的记录改写:不另挑更新的记录去补,也不被它顶掉 + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.identity == publications.PROVEN and judged.code is None + # K05 的卡级结论按的是最新那条:草稿页上看到的就是「这一次没过」 + async with SessionLocal() as session: + rows = await validation.list_for_draft(session, asset["draft_id"]) + current = validation.materials(asset["graph"], CARD, workflow_id=asset["workflow_id"]) + assert validation.summarize(rows, current=current)["verdict"] == later + # 重新发布等于按现在的记录重新认可这一版:最新的那条不是 matched,旧的不得顶上 + out = await publish(client, asset) + assert out["publication"]["proven"] is False + assert out["publication"]["problems"][0]["code"] == publications.RECORD_NOT_MATCHED + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == publications.RECORD_NOT_MATCHED + + +async def test_issue_on_a_legacy_asset_keeps_its_behaviour(client): + """加发布清单这一机制之前发布的资产(这一版没有清单):按口径出具照旧按原来的说法判,身份记 formal_legacy。""" + from app.ledger import issue as ledger_issue + + workflow_id = await S.publish() # 直接写库(老写法,不经过发布入口) + async with SessionLocal() as session: + workflow = await session.get(Workflow, workflow_id) + workflow.tags = ["doc_draft"] # 已接管,但没有清单 + await session.commit() + async with SessionLocal() as session: + plan = await issue_plan(session, {"workflow_id": workflow_id, "version": 1}) + assert "发布依据" not in (plan.reason or ""), plan.reason + assert plan.publication["identity"] == publications.LEGACY + assert plan.publication["requires_proof"] is False and plan.publication["manifest"] is None + + +# -------------------------------------------------------------------------- +# 7、清单得是这一版这一张图的;发布时的严格性记在事件行上 +# -------------------------------------------------------------------------- + + +async def test_a_strict_publication_keeps_its_strictness_after_a_tag_change(client): + """发布时按严格记下的一版:之后把接管标记去掉(清 tags)也不降级——事件行上的 required 说了算。""" + from app.engine.launch import LaunchRefused + + asset = await make_workflow() # tags=["doc_draft"]、没有 origin.kind + out = await publish(client, asset) + assert out["publication"]["required"] is True and out["publication"]["proven"] is False + assert (await latest_event(asset["workflow_id"], 1)).required is True + # 直接清掉标记:API 会拒(见下一节),这里演的是别的路径/老数据把它清掉了 + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + workflow.tags = [] + await session.commit() + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.requires_proof is True and judged.code == publications.RECORD_MISSING + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == publications.RECORD_MISSING + # 重新发布才按现在的状态重判:这一回不算接管,记 required=False,身份 formal_unproven + again = await publish(client, asset) + assert again["publication"]["required"] is False + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.requires_proof is False and judged.identity == publications.UNPROVEN and judged.code is None + + +async def test_a_manifest_for_another_graph_is_refused(client): + """版本行上的图被别的工具改过(清单还是这张图当时的):formal 和出具都按 BASIS_MISMATCH 拒,不拿它顶。""" + from app.engine.launch import LaunchRefused + from app.ledger import issue as ledger_issue + + asset = await make_workflow() + record_id = await add_record(asset) + await confirm(asset, record_id) + assert (await publish(client, asset))["publication"]["proven"] is True + async with SessionLocal() as session: + row = await _version_row(session, asset) + row.graph = S.caliber_graph(S.TEMPLATE.replace("'paid'", "'open'")) # 同一版号、换了图 + await session.commit() + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + resolved = await publications.resolve(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + plan = await issue_plan(session, asset) + assert resolved.publication_problem and resolved.publication_problem["code"] == publications.BASIS_MISMATCH + assert "图指纹" in resolved.publication_problem["message"] + assert judged.code == publications.BASIS_MISMATCH and judged.identity == publications.UNPROVEN + assert plan.code == publications.BASIS_MISMATCH + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == publications.BASIS_MISMATCH + + +async def test_a_manifest_missing_a_card_is_refused_without_padding(client): + """清单里没有图上的某张源头口径卡:按 BASIS_MISMATCH 拒,**不去库里另挑一条记录补上**。 + + 清单可能不是本代码写的(更早一版、别的工具):这里直接写一份图指纹对得上、但少了 card2 那一段的工件,再把事件 + 行指过去——比的是**工件内容**,事件行上的 cards 列说什么都不算。""" + from app.core.artifact_store import put_json + from app.engine.launch import LaunchRefused + + asset = await make_workflow(graph=two_card_graph()) + record_id = await add_record(asset) # 先只覆盖 card + await confirm(asset, record_id) + await publish(client, asset) + # card2 现在也有 matched + 审阅了:库里挑得到,但这一版的清单里根本没有它那一条 + other = await add_record(asset, card_id="card2", metric_ids=("refunds",)) + await confirm(asset, other, scope=["refunds"]) + async with SessionLocal() as session: + row = await publications.latest(session, asset["workflow_id"], 1) + content = publications.read(row) + content["cards"] = [card for card in content["cards"] if card["card_id"] != "card2"] + row.manifest = await put_json(content, kind=publications.KIND, run_id=None) + await session.commit() + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + resolved = await publications.resolve(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert resolved.publication_problem["card_id"] == "card2" + assert resolved.publication_problem["code"] == publications.BASIS_MISMATCH + assert judged.code == publications.BASIS_MISMATCH and judged.identity == publications.UNPROVEN + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == publications.BASIS_MISMATCH + + +async def test_the_comparison_follows_the_artifact_not_the_event_row(client): + """以工件内容为准:事件行的 cards 列被改过(可变的那几列)不影响判定,照旧按工件那一份认。""" + asset = await make_workflow() + record_id = await add_record(asset) + await confirm(asset, record_id) + assert (await publish(client, asset))["publication"]["proven"] is True + async with SessionLocal() as session: + row = await publications.latest(session, asset["workflow_id"], 1) + row.cards = [] # 事件行的摘要被抹掉(工件一个字没动) + await session.commit() + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + resolved = await publications.resolve(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert resolved.publication_content and resolved.publication_problem is None + assert judged.identity == publications.PROVEN and judged.problems == () + + +async def test_a_legacy_version_has_no_manifest_to_check(client): + """老资产(这一版没有发布事件):没有清单可核,resolve 的结论是 None、judge 记 formal_legacy,按原行为走。""" + workflow_id = await S.publish() + async with SessionLocal() as session: + workflow = await session.get(Workflow, workflow_id) + workflow.tags = ["doc_draft"] + await session.commit() + async with SessionLocal() as session: + workflow = await session.get(Workflow, workflow_id) + resolved = await publications.resolve(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert resolved.publication is None and resolved.publication_problem is None + assert judged.identity == publications.LEGACY and judged.code is None and judged.requires_proof is False + + +# -------------------------------------------------------------------------- +# 8、已接管的资产不能经普通 PATCH 把自己降成普通工作流 +# -------------------------------------------------------------------------- + + +async def test_the_takeover_tag_cannot_be_cleared_through_the_workflow_api(client): + """只靠标签认接管的那类资产:PATCH 清掉标记被拒(会同时关掉 K02 的并发保护和 K07 的严格性),标签原样留着。""" + from app.api.workflows import PROTECTED_ASSET + + asset = await make_workflow() # tags=["doc_draft"]、没有 origin.kind + res = await client.patch(f"/api/workflows/{asset['workflow_id']}", json={"tags": []}) + assert res.status_code == 409 and res.json()["code"] == PROTECTED_ASSET + assert "接管" in res.json()["detail"] + assert (await persisted(asset["workflow_id"])).tags == ["doc_draft"] + # 保护一个都没丢:清完标记这一步没生效,改图照旧要带基准版本(K02) + patch = await client.patch(f"/api/workflows/{asset['workflow_id']}", json={"graph": asset["graph"]}) + assert patch.status_code == 409 and patch.json()["code"] == "revision_required" + # 别的标签照旧增改,标记留着就行 + ok = await client.patch(f"/api/workflows/{asset['workflow_id']}", json={"tags": ["doc_draft", "周销售"]}) + assert ok.status_code == 200 and (await persisted(asset["workflow_id"])).tags == ["doc_draft", "周销售"] + + +async def test_ordinary_workflows_are_not_touched_by_that_guard(client): + """纯普通资产照旧随便改标签;origin 里记着文档起草的资产也不靠标签认接管,标签清空不算「降级」。""" + plain = await make_workflow(tags=["blueprint"]) + res = await client.patch(f"/api/workflows/{plain['workflow_id']}", json={"tags": []}) + assert res.status_code == 200 and (await persisted(plain["workflow_id"])).tags == [] + marked = await make_workflow(tags=[]) + async with SessionLocal() as session: + workflow = await session.get(Workflow, marked["workflow_id"]) + workflow.origin = {"kind": "doc_draft"} + await session.commit() + res = await client.patch(f"/api/workflows/{marked['workflow_id']}", json={"tags": ["周销售"]}) + assert res.status_code == 200 and (await persisted(marked["workflow_id"])).tags == ["周销售"] + + +# -------------------------------------------------------------------------- +# 9、转抄卡(caliber_from):上游那张卡按同一个用途递归判 +# -------------------------------------------------------------------------- + + +def chained_graph(upstream: dict, *, upstream_card: str = CARD) -> dict: + """下游的图:取数还是本地的,图上那张口径卡转抄上游某一版的那一张(caliber_from)——图里没有源头口径卡。""" + graph = S.caliber_graph() + card = next(node for node in graph["nodes"] if node["id"] == CARD) + card["data"]["config"] = {"caliber_from": {"workflow_id": upstream["workflow_id"], + "workflow_version": upstream["version"], + "node_id": upstream_card}} + return graph + + +async def verified_upstream(client, *, graph: dict | None = None, card_id: str = CARD, + metric_ids: tuple[str, ...] = ("gmv",)) -> dict: + """一个已接管、已按新发布入口发布、依据齐全的上游(口径库)。""" + upstream = await make_workflow(graph=graph) + record_id = await add_record(upstream, card_id=card_id, metric_ids=metric_ids) + await confirm(upstream, record_id, scope=list(metric_ids)) + assert (await publish(client, upstream))["publication"]["proven"] is True + return upstream + + +async def test_a_downstream_that_only_copies_an_unproven_upstream_is_refused(client): + """只含转抄卡的下游(自己 cards=[]):上游那一张卡没有发布依据时,下游也拿不到正式身份。""" + from app.engine.launch import LaunchRefused + from app.ledger import issue as ledger_issue + + upstream = await make_workflow() # 已接管、没有任何验证记录 + await publish(client, upstream) + assert (await latest_event(upstream["workflow_id"], 1)).proven is False + asset = await make_workflow(graph=chained_graph(upstream)) + await publish(client, asset) + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + plan = await issue_plan(session, asset) + # 机器码是上游那一条,问题点名下游的节点并带上游引用(可追) + assert judged.code == publications.RECORD_MISSING and judged.identity == publications.UNPROVEN + [found] = judged.problems + assert found["upstream"] == {"node_id": "card", "workflow_id": upstream["workflow_id"], "version": 1, + "card_id": CARD} + assert "转抄的" in found["message"] and "没有留下任何验证记录" in found["message"] + assert plan.code == publications.RECORD_MISSING + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == publications.RECORD_MISSING + assert "转抄的" in caught.value.message + + +async def test_a_downstream_with_a_verified_upstream_is_allowed(client, monkeypatch): + """上游那张卡依据齐全(成功上游),下游才允许:身份 formal_proven,正式运行发得起来。""" + report_model(monkeypatch) + upstream = await verified_upstream(client) + asset = await make_workflow(graph=chained_graph(upstream)) + await publish(client, asset) + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.refusal is None and judged.requires_proof is True + assert judged.identity == publications.PROVEN and judged.problems == () + run = await launch_formal(asset) + info = publication_of(run) + assert info["identity"] == publications.PROVEN and info["requires_proof"] is True + assert (await wait_run(run.id)).status == "succeeded" + + +async def test_only_the_referenced_card_of_the_upstream_matters(client): + """只判被引用的那一张卡:上游同工作流里别的卡没验证,不牵连下游;被引用的那张没验证,照旧拦。""" + from app.engine.launch import LaunchRefused + + # 上游两张卡,只验证 card:下游引用的正是它,另一张(card2)没依据,下游不受牵连 + upstream = await make_workflow(graph=two_card_graph()) + record_id = await add_record(upstream, card_id=CARD, metric_ids=("gmv",)) + await confirm(upstream, record_id, scope=["gmv"]) + out = await publish(client, upstream) + assert out["publication"]["proven"] is False # 上游自己那一版依据不齐(card2) + assert [p["card_id"] for p in out["publication"]["problems"]] == ["card2"] + asset = await make_workflow(graph=chained_graph(upstream)) + await publish(client, asset) + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.refusal is None and judged.identity == publications.PROVEN, judged.problems + # 反过来:只验证 card2,下游引用的 card 没依据 → 拦 + other = await make_workflow(graph=two_card_graph()) + record_id = await add_record(other, card_id="card2", metric_ids=("refunds",)) + await confirm(other, record_id, scope=["refunds"]) + await publish(client, other) + asset2 = await make_workflow(graph=chained_graph(other)) + await publish(client, asset2) + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset2["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.code == publications.RECORD_MISSING + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset2) + assert caught.value.code == publications.RECORD_MISSING + + +async def test_a_legacy_upstream_is_not_upgraded(client): + """上游那一版没有发布事件(老资产):明确不升级——下游照旧按原行为走,不替它补一道新门禁。""" + upstream_id = await S.publish() # 直接写库(老写法,没有发布事件) + asset = await make_workflow(graph=chained_graph({"workflow_id": upstream_id, "version": 1})) + await publish(client, asset) + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.refusal is None and judged.identity == publications.UNPROVEN + assert judged.requires_proof is False + + +async def test_an_upstream_outside_the_proof_scope_is_not_made_stricter(client): + """上游那一版不要求证明(不在证明范围内):下游不另立一套更严的说法——上游自己发起也就是 formal_unproven。""" + upstream = await make_workflow(tags=[]) # 手建的画布工作流 + await publish(client, upstream) + assert (await latest_event(upstream["workflow_id"], 1)).required is False + asset = await make_workflow(graph=chained_graph(upstream)) + await publish(client, asset) + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.refusal is None and judged.requires_proof is False + assert judged.identity == publications.UNPROVEN + + +async def test_a_cycle_between_two_chained_assets_terminates(client): + """循环引用(A 的卡转抄 B、B 的卡又转抄回 A):判得下去,不转圈,也不凭空报一条。""" + a = await make_workflow() + b = await make_workflow() + async with SessionLocal() as session: + for asset, other in ((a, b), (b, a)): + row = await _version_row(session, asset) + row.graph = chained_graph(other) + await session.commit() + await publish(client, a) + await publish(client, b) + async with SessionLocal() as session: + workflow = await session.get(Workflow, a["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + # 两边图里都没有源头口径卡:链子转回自己就截断,没有可判的依据 + assert judged.problems == () + + +async def test_a_two_hop_chain_judges_the_terminal_card(client): + """两层转抄:下游 → 中间那一版的转抄卡 → 上游的源头卡;判到源头卡那一层。""" + from app.engine.launch import LaunchRefused + + source = await make_workflow() # 源头:有卡、没有记录 + await publish(client, source) + middle = await make_workflow(graph=chained_graph(source)) # 中间:转抄源头那张卡 + await publish(client, middle) + asset = await make_workflow(graph=chained_graph(middle)) # 下游:转抄中间那一版的那张卡 + await publish(client, asset) + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.code == publications.RECORD_MISSING + assert judged.problems[0]["upstream"]["workflow_id"] == middle["workflow_id"] + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == publications.RECORD_MISSING + + +# -------------------------------------------------------------------------- +# 10、默认发起与点名版本:运行来源里的 explicit +# -------------------------------------------------------------------------- + + +async def test_a_default_launch_records_the_recommended_version_as_not_explicit(client, monkeypatch): + """默认发起(不传 version):只按工作流上的推荐指针取一次并固定,运行来源里 explicit=false; + 点名版本才是 true。并发下指针就算漂了,这一次用的还是发起那一刻定下来的那一版。""" + report_model(monkeypatch) + asset = await make_workflow() + record_id = await add_record(asset) + await confirm(asset, record_id) + await publish(client, asset) + asset = await add_version(asset, S.caliber_graph(S.TEMPLATE.replace("'paid'", "'open'")), version=2) + await publish(client, asset, version=2) + await publish(client, asset, version=1) # 把 v1 重新推上去(推荐版是 1,最高版是 2) + + resolved: list[str] = [] + original = publications.recommended + + async def counted(session, workflow): + resolved.append(workflow.id) + return await original(session, workflow) + + monkeypatch.setattr(publications, "recommended", counted) + # 默认发起:不传 version(launch_formal 会带上资产当前的版本,这里直接调 launch_run) + from app.engine.launch import launch_run + + async with SessionLocal() as session: + run = await launch_run(session, workflow_id=asset["workflow_id"], run_class="formal", actor="发布人", + input_payload={"start": "2026-09-01", "end": "2026-09-08"}, + origin_kind="launcher") + assert run.version == 1, "默认发起用的是推荐版" + assert resolved == [], "只读一次推荐指针(工作流上的),不再解析一遍推荐版" + info = publication_of(run) + assert info["explicit"] is False and info["version"] == 1 + assert (await wait_run(run.id)).status == "succeeded" + monkeypatch.setattr(publications, "recommended", original) # 只还原这一处(report_model 的假模型还要用) + named = await launch_formal(asset, version=1) # 点名版本 + assert publication_of(named)["explicit"] is True + assert (await wait_run(named.id)).status == "succeeded" + + +# -------------------------------------------------------------------------- +# 11、三层转抄链(D → M → S):链子上哪一层坏了都拦,问题逐层保留、可追 +# -------------------------------------------------------------------------- + + +async def three_layer_chain(client, *, source_verified: bool = True) -> dict: + """D → M → S:S 是源头口径库、M 转抄 S、D 转抄 M。S 参差(默认依据齐全)。""" + source = (await verified_upstream(client) if source_verified + else await make_workflow()) + if not source_verified: + await publish(client, source) + middle = await make_workflow(graph=chained_graph(source)) + await publish(client, middle) + top = await make_workflow(graph=chained_graph(middle)) + await publish(client, top) + return {"d": top, "m": middle, "s": source} + + +def _drop_resolver(row) -> dict: + content = publications.read(row) + content["compiler"].pop("resolver") + return content + + +@pytest.mark.parametrize("broken,code", [("missing", publications.MANIFEST_MISSING), + ("tampered", publications.MANIFEST_TAMPERED), + ("compiler", publications.COMPILER_MISMATCH)]) +async def test_a_broken_middle_layer_stops_the_whole_chain(client, broken, code): + """D → M → S:S 依据齐全也不能让 D 拿到 formal_proven——M 这一层的清单坏了就整条链子拦,问题追到 M 那一层。""" + from app.core.artifact_store import put_json + from app.engine.launch import LaunchRefused + + chain = await three_layer_chain(client) + row = await latest_event(chain["m"]["workflow_id"], 1) + path = artifact_store._path_of(row.manifest) + if broken == "missing": + path.unlink() + elif broken == "tampered": + path.write_text(path.read_text(encoding="utf-8").replace('"level":"published"', '"level":"governed"'), + encoding="utf-8") + else: + async with SessionLocal() as session: + stored = await publications.latest(session, chain["m"]["workflow_id"], 1) + stored.manifest = await put_json(_drop_resolver(stored), kind=publications.KIND, run_id=None) + await session.commit() + async with SessionLocal() as session: + workflow = await session.get(Workflow, chain["d"]["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + plan = await issue_plan(session, chain["d"]) + assert judged.code == code and judged.identity == publications.UNPROVEN + [found] = judged.problems + # 问题出在 M 这一层:引用链只有 D 的节点 → M 这一跳,链路终点就是 M + assert [hop["workflow_id"] for hop in found["trace"]] == [chain["m"]["workflow_id"]] + assert found["trace"][-1]["workflow_id"] == chain["m"]["workflow_id"] + assert found["upstream"]["workflow_id"] == chain["m"]["workflow_id"] + assert found["card_id"] == CARD and "转抄的" in found["message"] + assert chain["s"]["workflow_id"] not in found["message"] + assert plan.code == code + with pytest.raises(LaunchRefused) as caught: + await launch_formal(chain["d"]) + assert caught.value.code == code + + +async def test_every_layer_of_the_chain_keeps_its_own_problem(client): + """链子上两层都坏了(M 的清单没了、S 的清单也没了):两条都在、各带各的引用链,不合成一条。""" + from app.engine.launch import LaunchRefused + + chain = await three_layer_chain(client) + for who in ("m", "s"): + row = await latest_event(chain[who]["workflow_id"], 1) + artifact_store._path_of(row.manifest).unlink() + async with SessionLocal() as session: + workflow = await session.get(Workflow, chain["d"]["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.code == publications.MANIFEST_MISSING and judged.identity == publications.UNPROVEN + assert len(judged.problems) == 2, judged.problems + chains = {tuple(hop["workflow_id"] for hop in found["trace"]) for found in judged.problems} + assert chains == {(chain["m"]["workflow_id"],), (chain["m"]["workflow_id"], chain["s"]["workflow_id"])} + for found in judged.problems: + assert found["code"] == publications.MANIFEST_MISSING and found["card_id"] == CARD + assert "转抄的" in found["message"] and "发布清单工件不在了" in found["message"] + with pytest.raises(LaunchRefused) as caught: + await launch_formal(chain["d"]) + assert caught.value.code == publications.MANIFEST_MISSING + + +async def test_a_broken_layer_keeps_its_problem_when_the_reference_points_nowhere(client): + """被引用的那张卡在图里找不到(nested_node 为空):这一层的问题照样保留,不因为往下没得判就放过。""" + from app.engine.launch import LaunchRefused + + chain = await three_layer_chain(client) + # M 引用的卡 id 在 S 的图上不存在(图检查只管形状,具体有没有这个节点由运行时判) + async with SessionLocal() as session: + row = await _version_row(session, chain["m"]) + graph = row.graph + card = next(node for node in graph["nodes"] if node["id"] == CARD) + card["data"]["config"]["caliber_from"]["node_id"] = "not-there" + row.graph = graph + await session.commit() + middle_row = await latest_event(chain["m"]["workflow_id"], 1) + artifact_store._path_of(middle_row.manifest).unlink() + async with SessionLocal() as session: + workflow = await session.get(Workflow, chain["d"]["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.code == publications.MANIFEST_MISSING and judged.identity == publications.UNPROVEN + assert [hop["workflow_id"] for hop in judged.problems[0]["trace"]] == [chain["m"]["workflow_id"]] + with pytest.raises(LaunchRefused) as caught: + await launch_formal(chain["d"]) + assert caught.value.code == publications.MANIFEST_MISSING + + +async def test_a_broken_layer_still_counts_when_another_layer_requires_proof(client): + """链子上只要有一层要求证明,别的层的工件问题也保留:M 不做证明(手建的),D 和 S 要——M 的清单没了照样拦。""" + chain = await three_layer_chain(client) + async with SessionLocal() as session: # M 改成手建的口径库:它自己不再要求证明 + workflow = await session.get(Workflow, chain["m"]["workflow_id"]) + workflow.tags = [] + await session.commit() + row = await latest_event(chain["m"]["workflow_id"], 1) + assert row.required is False and row.proven is False + artifact_store._path_of(row.manifest).unlink() + async with SessionLocal() as session: + workflow = await session.get(Workflow, chain["d"]["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.code == publications.MANIFEST_MISSING and judged.identity == publications.UNPROVEN + assert [hop["workflow_id"] for hop in judged.problems[0]["trace"]] == [chain["m"]["workflow_id"]] + + +async def test_a_chain_that_asks_nothing_of_any_layer_is_left_alone(client): + """链子上没有任何一层要求证明(都是手建的工作流、发布时也没要求):不升级——M 的清单坏了也不拦。""" + source = await make_workflow(tags=[]) # 手建的口径库 + await publish(client, source) + middle = await make_workflow(graph=chained_graph(source), tags=[]) + await publish(client, middle) + top = await make_workflow(graph=chained_graph(middle), tags=[]) + await publish(client, top) + row = await latest_event(middle["workflow_id"], 1) + assert row.required is False + artifact_store._path_of(row.manifest).unlink() + async with SessionLocal() as session: + workflow = await session.get(Workflow, top["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.refusal is None and judged.problems == () + assert judged.requires_proof is False and judged.identity == publications.UNPROVEN diff --git a/backend/tests/test_publication_manifest.py b/backend/tests/test_publication_manifest.py new file mode 100644 index 00000000..e65cfb5f --- /dev/null +++ b/backend/tests/test_publication_manifest.py @@ -0,0 +1,554 @@ +"""K07 的发布依据:不可变清单、发布事件、版本解析(任务书 4.9 与 E10)。 + +这份文件盯住几件不变量: + +1. **每次发布留一份不可变清单 + 追加一行发布事件。** 清单是内容寻址工件,固定图/定义/绑定/参数契约/依赖/编译器与 + 验证方法版本,以及发布这一刻引用的 ValidationRecord / ReviewDecision。 +2. **重发旧版产生新事件,旧事件和旧清单一个字不改**(E10):版本行上那几列发布元数据是最新投影,指针 + Workflow.published_version 是推荐指针。 +3. **默认调用读推荐版**:目录(descriptor)、look、账本挑候选一致;最高已发布版只用于升级发现。 +4. **显式版本始终固定**:点名哪一版就是哪一版。 +5. **清单尽量确定**:内容里没有 actor、没有时间;原始输入还在时按它重建一字不差,原始输入缺失/工件读不出来明确失败。 + **观察到的环境(目录/结构/能力版本、绑定工具在不在)不进内容**:环境变了重发同一版,清单一字不差,变化只记在事件行上。 +6. **发布失败无事件**:发布这一步没提交,事件也不会落。事件和版本行上的最新投影同一个事务:没提交之前别的会话看不到, + 回滚之后一个字都不留。 +7. **发布只有一个入口**:只有 app/apps/publications.py 建 WorkflowPublication 行,接口和发布单都走 commit_publish。 +8. **清单工件没有运行引用也不被回收**:put_json 记了一行 run_id 为空的引用,评测回收(artifact_store.forget)按引用数删, + 这一份照留。 +9. **发布这一刻的严格性记在事件行上**(WorkflowPublication.required):之后清掉接管标记也不降级。加这一列之前的事件行 + 由迁移回填 0,判定照旧看当前的接管状态(补 0 不放松)。 +10. **每次有发布事件的执行都复验工件与编译器约定**(`verified_content` = read 复验 + compiler_problems,和 K09 的 + 固定执行同一份核对):清单工件被删/被改过、按别的约定物化的,正式运行与出具都拒;legacy(没有事件)没有清单可复验, + 保持原行为。比的一律是**工件内容**,不认可变的事件行列。 + +数据是虚构店铺库(tests/ledger_samples),不连真实业务库。 +""" +from __future__ import annotations + +from pathlib import Path + +import pytest +from httpx import ASGITransport, AsyncClient +from sqlalchemy import select + +from app.api.workflows import commit_publish +from app.apps import publications +from app.core import artifact_store +from app.core.artifact_store import canonical_json, graph_hash +from app.db.base import SessionLocal +from app.db.models import Artifact, CaliberValidationRecord, DataSource, Workflow, WorkflowVersion +from app.engine.runner import run_manager +from app.ledger import validation +from app.main import app +from tests import ledger_samples as S +from tests.publication_samples import (CARD, add_record, add_version, confirm, events_of, issue_plan, + launch_formal, latest_event, make_workflow, persisted, publication_of, publish, + report_model, version_row) + +#: 另一份「只算已支付」改成「算所有状态」的取数(定义/取数都变了) +OTHER_GRAPH = S.caliber_graph(S.TEMPLATE.replace("'paid'", "'open'")) + + +@pytest.fixture(autouse=True) +async def engine_up(tmp_path): + await run_manager.setup() + await S.fresh_source(tmp_path / "shop.db") + yield + await run_manager.shutdown() + + +@pytest.fixture +async def client(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c: + yield c + + +# -------------------------------------------------------------------------- +# 1、每次发布留一份清单 + 一行事件 +# -------------------------------------------------------------------------- + + +async def test_publishing_leaves_a_manifest_and_an_event(client): + asset = await make_workflow() + record_id = await add_record(asset) + review_id = await confirm(asset, record_id) + out = await publish(client, asset) + assert out["ok"] and out["version"] == 1 + assert out["manifest"] and out["publication"]["manifest"] == out["manifest"] + assert out["publication"]["proven"] is True and out["publication"]["required"] is True + assert out["publication"]["problems"] == [] + # 旧返回键一个不动 + assert out["level"] == "published" and out["graph_hash"] and out["published_by"] == "小王" + events = await events_of(asset["workflow_id"], 1) + assert len(events) == 1 and events[0].manifest == out["manifest"] + assert events[0].actor == "小王" and events[0].level == "published" + assert (await persisted(asset["workflow_id"])).published_version == 1 + async with SessionLocal() as session: + content = publications.read(await publications.latest(session, asset["workflow_id"], 1)) + assert content["workflow_id"] == asset["workflow_id"] and content["version"] == 1 + assert content["graph_hash"] == graph_hash(asset["graph"]) + [card] = content["cards"] + assert card["card_id"] == CARD and card["metric_ids"] == ["gmv"] + assert card["definition_hash"] and card["semantic_hash"] + assert card["binding_status"] == "unbound" # 这张卡没声明业务字段:不判同步 + assert card["validation"]["record_id"] == record_id and card["validation"]["status"] == "matched" + assert card["review"]["decision_id"] == review_id and card["review"]["decision"] == "confirmed" + assert card["review"]["scope"] == ["gmv"] and card["proof"]["ok"] is True + # 参数契约、依赖、编译器与验证方法版本都固定下来了 + assert [f["name"] for f in content["parameters"]] == ["start", "end", "store"] + assert content["dependencies"]["sources"] == [S.CURRENT["source"]] + assert content["dependencies"]["tables"] == ["orders"] + assert content["compiler"]["binding"]["binder"] == "controlled_template" + assert content["compiler"]["validation_method"] == validation.METHOD_VERSION + # 版本详情里也看得到这一版按哪份清单发布的(老资产是 null) + detail = (await client.get(f"/api/workflows/{asset['workflow_id']}/versions/1")).json() + assert detail["publication"]["manifest"] == out["manifest"] and detail["publication"]["proven"] is True + assert detail["publication"]["problems"] == [] + + +async def test_the_manifest_holds_no_actor_and_no_time(client): + """清单要被重建,所以内容里不能有会变的东西:发布人、时间、目录/能力版本、工具在不在都不进内容(记在事件行上)。""" + asset = await make_workflow() + await publish(client, asset) + row = await latest_event(asset["workflow_id"], 1) + text = canonical_json(publications.read(row)) + assert "小王" not in text and "actor" not in text and "published_at" not in text and "created_at" not in text + assert row.observed["at"] and "catalog_versions" in row.observed and "missing_tools" in row.observed + assert isinstance(row.observed["capability_versions"], dict) and row.observed["capability_versions"] + assert "capability_versions" not in text and "catalog_versions" not in text + + +# -------------------------------------------------------------------------- +# 2、E10:重发旧版 +# -------------------------------------------------------------------------- + + +async def test_republishing_an_old_version_appends_and_never_rewrites(client): + asset = await make_workflow() + record_id = await add_record(asset) + await confirm(asset, record_id) + first = await publish(client, asset) # v1 + asset = await add_version(asset, OTHER_GRAPH, version=2) # 图上改了取数 + second = await publish(client, asset, version=2) + third = await publish(client, asset, version=1) # 把旧版 v1 重新推上去 + assert first["manifest"] == third["manifest"], "v1 两次发布的依据一模一样(引用的记录没变)" + assert second["manifest"] != first["manifest"] + # 重发不是「继承」身份,而是按这一版重新核对:v2 的定义/取数改过,老记录不覆盖它,依据不齐;回到 v1 又对上了 + assert second["publication"]["proven"] is False + assert second["publication"]["problems"][0]["code"] == "publication_record_stale" + assert third["publication"]["proven"] is True and third["publication"]["problems"] == [] + # 推荐指针跟着最新一次发布事件走 + assert (await persisted(asset["workflow_id"])).published_version == 1 + v1_events = await events_of(asset["workflow_id"], 1) + assert len(v1_events) == 2 and v1_events[0].manifest == first["manifest"] + assert v1_events[1].manifest == first["manifest"] and v1_events[1].id != v1_events[0].id + v2_events = await events_of(asset["workflow_id"], 2) + assert len(v2_events) == 1 and v2_events[0].manifest == second["manifest"] + # v2 那一行一个字没改 + async with SessionLocal() as session: + v2 = await publications.latest(session, asset["workflow_id"], 2) + assert v2.cards == v2_events[0].cards and v2.proven is False + assert publications.read(v2)["version"] == 2 + + +async def test_default_calls_follow_the_recommended_version_and_the_upgrade_hint(client): + """目录、look、账本挑候选读推荐版;最高已发布版只用来提示「有一版更新的」。""" + from app.ledger import descriptor + from app.ledger import match as ledger_match + from app.look.calibers import CaliberKind + + asset = await make_workflow() + await publish(client, asset) + asset = await add_version(asset, OTHER_GRAPH, version=2) + await publish(client, asset, version=2) + await publish(client, asset, version=1) # 重新推上一版旧版 + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + recommended = await publications.recommended(session, workflow) + assert recommended.version == 1 + assert (await publications.highest(session, workflow.id)).version == 2 + assert (await publications.upgrade_of(session, workflow))["version"] == 2 + described = {item["workflow_id"]: item for item in await descriptor.list_calibers(session)}[workflow.id] + assert described["version"] == 1 and described["publication"]["manifest"] + kind = await CaliberKind.load(session) + assert {i.version for i in kind.items if i.workflow_id == workflow.id} == {1} + candidates = {c.workflow_id: c for c in await ledger_match.load_calibers(session)} + assert candidates[workflow.id].version == 1 + # 图里两条 SQL 的差别就是「只算已支付」:候选取的是 v1(推荐版)那一版的取数 + [fetch] = candidates[workflow.id].fetches + assert "paid" in fetch.sql + # 显式版本始终固定 + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + pinned = await publications.resolve(session, workflow, version=2, purpose=publications.PURPOSE_FORMAL) + assert pinned.version == 2 and pinned.explicit is True + follow = await publications.resolve(session, workflow, purpose=publications.PURPOSE_EXPLORE) + assert follow.version == 1 and follow.explicit is False + assert (await descriptor.caliber_descriptor(session, workflow.id, 2, CARD))["version"] == 2 + + +# -------------------------------------------------------------------------- +# 3、清单:可读、可重建、不可读与原始输入缺失都明确失败 +# -------------------------------------------------------------------------- + + +async def test_the_manifest_rebuilds_to_the_same_bytes(client): + asset = await make_workflow() + record_id = await add_record(asset) + await confirm(asset, record_id) + out = await publish(client, asset) + async with SessionLocal() as session: + row = await publications.latest(session, asset["workflow_id"], 1) + rebuilt = await publications.rebuild(session, row) + assert rebuilt["matches"] is True and rebuilt["computed"] == out["manifest"] + assert rebuilt["content"] == rebuilt["original"] and rebuilt["problems"] == [] + + +async def test_an_unreadable_or_missing_artifact_fails_explicitly(client): + asset = await make_workflow() + await publish(client, asset) + async with SessionLocal() as session: + row = await publications.latest(session, asset["workflow_id"], 1) + path = artifact_store._path_of(row.manifest) + original = path.read_text(encoding="utf-8") + # 被改过:读的时候复验哈希 + path.write_text(original.replace('"level":"published"', '"level":"governed"'), encoding="utf-8") + with pytest.raises(publications.PublicationUnreadable) as caught: + publications.read(row) + assert caught.value.code == publications.MANIFEST_TAMPERED + # 工件不见了 + path.unlink() + with pytest.raises(publications.PublicationUnreadable) as gone: + publications.read(row) + assert gone.value.code == publications.MANIFEST_MISSING + path.write_text(original, encoding="utf-8") + assert publications.read(row)["version"] == 1 + # 没有事件的那一版:没有依据 + with pytest.raises(publications.PublicationUnreadable) as nothing: + publications.read(None) + assert nothing.value.code == publications.BASIS_MISSING + + +async def test_missing_raw_inputs_fail_explicitly(client): + """原始输入(这一版不可变的图、引用的那两行记录)缺了一样就重建不上,明确失败,不拿别的版本顶。""" + asset = await make_workflow() + record_id = await add_record(asset) + await confirm(asset, record_id) + await publish(client, asset) + async with SessionLocal() as session: + record = await session.get(CaliberValidationRecord, record_id) + await session.delete(record) # 引用的验证记录被删(删草稿时级联删) + await session.commit() + row = await latest_event(asset["workflow_id"], 1) + assert publications.read(row)["cards"][0]["validation"]["record_id"] == record_id + async with SessionLocal() as session: + with pytest.raises(publications.PublicationUnreadable) as caught: + await publications.rebuild(session, row) + assert caught.value.code == publications.INPUTS_MISSING + # 版本行(这一版不可变的图)被删了:同样重建不上 + async with SessionLocal() as session: + version = (await session.execute(select(WorkflowVersion).where( + WorkflowVersion.workflow_id == asset["workflow_id"], + WorkflowVersion.version == 1))).scalar_one() + await session.delete(version) + await session.commit() + async with SessionLocal() as session: + with pytest.raises(publications.PublicationUnreadable) as gone: + await publications.rebuild(session, row) + assert gone.value.code == publications.INPUTS_MISSING + + +# -------------------------------------------------------------------------- +# 4、发布失败无事件;发布只有一个入口 +# -------------------------------------------------------------------------- + + +async def test_a_failed_publish_leaves_no_event(client): + asset = await make_workflow() + # 指名的版本不存在:404,没有事件 + res = await client.post(f"/api/workflows/{asset['workflow_id']}/publish", json={"level": "published", "version": 9}) + assert res.status_code == 404 + assert await events_of(asset["workflow_id"]) == [] + # 级别写坏了:400,没有事件 + bad = await client.post(f"/api/workflows/{asset['workflow_id']}/publish", json={"level": "gold"}) + assert bad.status_code == 400 + assert await events_of(asset["workflow_id"]) == [] + # 图过不了发布检查:ok=False,同样没有事件 + broken = S.chain(S.node("start", "input"), + S.node("out", "output", fields=[{"name": "x", "value": "{{ nodes.missing.text }}"}])) + asset = await add_version(asset, broken, version=2) + out = (await client.post(f"/api/workflows/{asset['workflow_id']}/publish", + json={"level": "published", "version": 2})).json() + assert out["ok"] is False and out["issues"] + assert await events_of(asset["workflow_id"]) == [] + + +def test_publishing_has_a_single_writer(): + """发布只有一个入口:只有 app/apps/publications.py 建发布事件行;接口和发布单都调 commit_publish。""" + root = Path(__file__).resolve().parents[1] / "app" + writers: list[str] = [] + for path in sorted(root.rglob("*.py")): + for line in path.read_text(encoding="utf-8").splitlines(): + code = line.strip() + if "WorkflowPublication(" in code and not code.startswith("class "): + writers.append(path.relative_to(root).as_posix()) + break + assert writers == ["apps/publications.py"] + callers = {path.relative_to(root.parent).as_posix() + for path in root.rglob("*.py") + if "commit_publish(" in path.read_text(encoding="utf-8")} + assert "app/api/workflows.py" in callers and "app/blueprints/publish_plan.py" in callers + # 发布单那一步也把这一次实际留下的清单交回(执行完能对上是哪一份) + plan = (root / "blueprints/publish_plan.py").read_text(encoding="utf-8") + assert 'out.get("manifest")' in plan + + +async def test_the_publish_plan_step_reports_the_same_manifest(client): + """发布单那一步走的是同一个 commit_publish:交回的就是这一次实际留下的清单;已经是这一档发布版时不再多发事件, + 但交回的还是那一次留下的那一份(发布依据只有一份,不会因为出单又补一份)。""" + from app.api.deps import Principal + from app.blueprints import publish_plan + + admin = Principal(username="boss", role="admin", mode="off", via="off") + + async def run_step(workflow_id: str, version: int) -> dict: + async with SessionLocal() as session: + ctx = publish_plan._Run(row=None, bp=None, principal=admin, actor="发布人", options={}, + level="published", + results={"save_version": {"workflow_id": workflow_id, "version": version}}) + out = await publish_plan._do_publish_workflow(session, ctx) + await session.commit() + return out + + asset = await make_workflow() + out = await run_step(asset["workflow_id"], 1) + assert out["manifest"] and out["proven"] is False, "这一步交回的是它刚留下的那一份发布依据" + [event] = await events_of(asset["workflow_id"], 1) + assert event.manifest == out["manifest"] and out["publication_id"] == event.id + # 再执行一次同一步:已经是这一档的发布版,不再多发一次事件 + again = await run_step(asset["workflow_id"], 1) + assert again["already"] is True and again["manifest"] == event.manifest + assert len(await events_of(asset["workflow_id"], 1)) == 1 + + +# -------------------------------------------------------------------------- +# 5、事件与版本投影同一个事务;清单工件没有运行引用也不被回收;环境变化不改内容 +# -------------------------------------------------------------------------- + + +async def _row_in(session, asset: dict) -> WorkflowVersion: + """这个会话里这一版的版本行(commit_publish 要的是同一个会话里的行)。""" + return (await session.execute(select(WorkflowVersion).where( + WorkflowVersion.workflow_id == asset["workflow_id"], + WorkflowVersion.version == asset["version"]))).scalar_one() + + +async def test_the_event_and_the_version_projection_are_one_transaction(client): + """发布事件和版本行上的最新投影同一个事务:没提交之前别的会话看不到,回滚之后一个字都不留(「发布失败无事件」)。""" + asset = await make_workflow() + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + out = await publications.publish(session, workflow=workflow, snapshot=await _row_in(session, asset), + level="published", actor="发布人") + async with SessionLocal() as other: + assert await publications.events(other, asset["workflow_id"]) == [], "没提交的发布事件不该被别的会话读到" + await session.rollback() + assert await events_of(asset["workflow_id"]) == [] + workflow = await persisted(asset["workflow_id"]) + assert workflow.published_version is None and workflow.published_by is None + # 提交了才是事件:走发布接口发布一次,指针和事件一起落;清单是内容寻址的,还是刚才那一份 + published = await publish(client, asset) + assert published["manifest"] == out["manifest"] + assert (await persisted(asset["workflow_id"])).published_version == 1 + assert len(await events_of(asset["workflow_id"], 1)) == 1 + + +async def test_the_manifest_artifact_is_kept_without_a_run(client): + """清单工件没有运行引用(run_id 为空),回收按引用数删:不挂运行的那一行也算引用,这一份照留。""" + asset = await make_workflow() + out = await publish(client, asset) + manifest = out["manifest"] + async with SessionLocal() as session: + rows = list((await session.execute(select(Artifact).where(Artifact.id == manifest))).scalars()) + assert [row.run_id for row in rows] == [""] and rows[0].kind == publications.KIND + assert await artifact_store.forget([manifest]) == [], "还有引用行的工件不该被回收" + assert artifact_store.load(manifest) is not None + async with SessionLocal() as session: + assert (await publications.rebuild(session, await publications.latest(session, asset["workflow_id"], 1)) + )["matches"] is True + + +async def test_the_manifest_does_not_depend_on_the_observed_environment(client): + """环境变了(数据源停用、绑定的工具现在不在本机)重发同一版:清单内容一字不差,变化只记在事件行上。""" + asset = await make_workflow() + first = await publish(client, asset) + async with SessionLocal() as session: + source = (await session.execute(select(DataSource).where( + DataSource.name == S.CURRENT["source"]))).scalar_one() + source.enabled = False + await session.commit() + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + second = await commit_publish(session, workflow, await _row_in(session, asset), "published", "发布人") + assert second["manifest"] == first["manifest"], "观察到的环境不进清单内容" + events = await events_of(asset["workflow_id"], 1) + assert len(events) == 2 and events[0].manifest == events[1].manifest + assert events[0].observed["missing_tools"], "工具现在不在本机这一件记在事件行上" + assert "missing_tools" not in canonical_json(publications.read(events[0])) + async with SessionLocal() as session: + assert (await publications.rebuild(session, events[0]))["matches"] is True + + +# -------------------------------------------------------------------------- +# 6、老库补 required 列(发布这一刻的严格性);补列之前的事件行照旧按当前状态判 +# -------------------------------------------------------------------------- + + +def test_an_old_database_gets_the_required_column(): + """老库补 workflow_publications.required:存量事件行回填 0;和后端启动同一套迁移,跑两遍不出错。""" + from sqlalchemy import create_engine, text + + from app.db.base import _migrate + + db = create_engine("sqlite://") + with db.begin() as conn: + conn.execute(text("CREATE TABLE workflow_publications (id VARCHAR(32) PRIMARY KEY, workflow_id VARCHAR(32), " + "version INTEGER, level VARCHAR(20), graph_hash VARCHAR(64), manifest VARCHAR(64))")) + conn.execute(text("INSERT INTO workflow_publications (id, workflow_id, version, level, manifest) " + "VALUES ('p1', 'w1', 1, 'published', 'm1')")) + _migrate(conn) + _migrate(conn) # 再执行一次不出错:列已经在了 + cols = {row[1] for row in conn.execute(text("PRAGMA table_info(workflow_publications)"))} + assert "required" in cols + assert conn.execute(text("SELECT required FROM workflow_publications WHERE id = 'p1'")).scalar() == 0 + + +async def test_an_event_without_the_flag_still_follows_the_current_state(client): + """补列之前留下的事件行(required 是回填的 0):判定照旧看当前的接管状态,不会因为补了个 0 就不要求证明。""" + asset = await make_workflow() # 已接管、还没有任何验证记录 + await publish(client, asset) + async with SessionLocal() as session: + row = await publications.latest(session, asset["workflow_id"], 1) + row.required = False # 存量行的样子 + await session.commit() + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.requires_proof is True and judged.code == publications.RECORD_MISSING + + +async def test_the_event_records_whether_this_version_needed_proof(client): + """事件行上记下发布这一刻要不要证明:接管着的记真;手建的工作流不在证明范围内,记假。""" + strict = await make_workflow() # tags=["doc_draft"]:已接管 + assert (await publish(client, strict))["publication"]["required"] is True + assert (await latest_event(strict["workflow_id"], 1)).required is True + plain = await make_workflow(tags=[]) # 手建的画布工作流 + out = await publish(client, plain) + assert out["publication"]["required"] is False + assert (await latest_event(plain["workflow_id"], 1)).required is False + + +# -------------------------------------------------------------------------- +# 7、每次有发布事件的执行都复验工件与编译器约定(和 K09 的固定执行同一份核对) +# -------------------------------------------------------------------------- + + +async def _point_at(session, row, content: dict) -> str: + """把事件行指向一份新写下的清单工件(内容寻址,读的时候复验哈希)。""" + from app.core.artifact_store import put_json + + row.manifest = await put_json(content, kind=publications.KIND, run_id=None) + await session.commit() + return row.manifest + + +@pytest.mark.parametrize("broken,code", [("missing", publications.MANIFEST_MISSING), + ("tampered", publications.MANIFEST_TAMPERED)]) +async def test_a_broken_manifest_stops_formal_runs(client, broken, code): + """清单工件被删、被改过:正式运行与按口径出具都拒——每次都复验工件,过关才继续。""" + from app.engine.launch import LaunchRefused + asset = await make_workflow() + record_id = await add_record(asset) + await confirm(asset, record_id) + assert (await publish(client, asset))["publication"]["proven"] is True + row = await latest_event(asset["workflow_id"], 1) + path = artifact_store._path_of(row.manifest) + if broken == "missing": + path.unlink() + else: + path.write_text(path.read_text(encoding="utf-8").replace('"level":"published"', '"level":"governed"'), + encoding="utf-8") + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + plan = await publications.resolve(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.code == code and judged.identity == publications.UNPROVEN + assert plan.publication_content is None and plan.publication_problem["code"] == code + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == code + async with SessionLocal() as session: + got = await issue_plan(session, asset) + assert got.code == code + + +async def test_a_broken_manifest_stops_runs_outside_the_proof_scope_too(client): + """不在证明范围内的资产(发布时 required=false):清单工件没了照样拒——事件说有清单,清单就得在。""" + from app.engine.launch import LaunchRefused + + asset = await make_workflow(tags=[]) # 手建的画布工作流:不需要证明 + await publish(client, asset) + row = await latest_event(asset["workflow_id"], 1) + assert row.required is False + artifact_store._path_of(row.manifest).unlink() + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == publications.MANIFEST_MISSING + + +@pytest.mark.parametrize("broken,code", [("no_compiler", publications.COMPILER_MISSING), + ("old_resolver", publications.COMPILER_MISMATCH)]) +async def test_a_manifest_written_under_another_compiler_is_refused(client, broken, code): + """清单是按别的约定物化的(整段没有 / 少了依赖闭包的解析器这一项):不按新规则重解释旧发布,正式运行拒。""" + from app.engine.launch import LaunchRefused + + asset = await make_workflow() + record_id = await add_record(asset) + await confirm(asset, record_id) + await publish(client, asset) + row = await latest_event(asset["workflow_id"], 1) + content = publications.read(row) + if broken == "no_compiler": + content.pop("compiler") + else: + content["compiler"].pop("resolver") + async with SessionLocal() as session: + stored = await publications.latest(session, asset["workflow_id"], 1) + await _point_at(session, stored, content) + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + judged = await publications.judge(session, workflow, version=1, purpose=publications.PURPOSE_FORMAL) + assert judged.code == code and judged.identity == publications.UNPROVEN + with pytest.raises(LaunchRefused) as caught: + await launch_formal(asset) + assert caught.value.code == code + + +async def test_a_legacy_version_without_any_manifest_still_runs(client, monkeypatch): + """legacy(这一版没有发布事件)没有清单可复验:保持原行为,正式运行照旧发得起来、身份 formal_legacy。""" + from tests.publication_samples import publication_of + + report_model(monkeypatch) + workflow_id = await S.publish() # 直接写库(老写法,没有发布事件、没有清单) + async with SessionLocal() as session: + workflow = await session.get(Workflow, workflow_id) + workflow.tags = ["doc_draft"] + await session.commit() + from app.engine.launch import launch_run + + async with SessionLocal() as session: + run = await launch_run(session, workflow_id=workflow_id, run_class="formal", actor="发布人", + input_payload={"start": "2026-09-01", "end": "2026-09-08"}) + assert run.version == 1 + assert publication_of(run)["identity"] == publications.LEGACY + assert publication_of(run)["manifest"] is None diff --git a/backend/tests/test_querycore_execute.py b/backend/tests/test_querycore_execute.py new file mode 100644 index 00000000..3c89f2ef --- /dev/null +++ b/backend/tests/test_querycore_execute.py @@ -0,0 +1,678 @@ +"""K09 的进程内 QueryCore 固定执行与最小 API(app/ledger/querycore.py、POST /api/ledger/querycore)。 + +这份文件盯住这几条: + +1. **版本只解析一次并固定。** 不点名读推荐版(Workflow.published_version 指的那一版)并固定到它;点名始终固定到点名的那一版。 +2. **只按固定发布执行。** 必须读并核验 K07 的发布清单(读得出来、内容哈希对得上、就是这一版这一张图);编译器/绑定/ + 参数/解析器约定不兼容、清单错图/缺卡一律明确拒,**绝不按新编译器现场重解释旧发布**;老资产(没有清单)明确拒, + 旧 trial 路径一个字不动。 +3. **用 K08 闭包选指标、K01 参数语义。** 选 A 时 B 独有的取数节点与参数不进这次范围;A、B 共用一条 SQL 时那条 SQL 保留并由 + computes_unselected 声明它还在算谁;缺参数/未声明参数在发 SQL 之前就拒(一条 SQL 都不发)。 +4. **内部 LLM = 0、作者侧 SQL 编译 = 0、零运行期重绑定。** 探针图里没有模型节点;执行过的语句与这次计划渲染出来的一致、 + 参数输入哈希一致。 +5. **类型化交回。** 大整数不转 float(精确整数原样);Decimal 过投影时换成精确文本并标成 decimal(接口把 Decimal 编码成 + float 会丢精度);带时区的取值原样进语句、原样回交(不 shift、不重解释)。 +6. **空数组与部分失败不冒充成功。** 没跑完(超时)回 running + run_id;没有值的指标、被遮罩的指标、没有快照的查询一律 + ok=False。 +7. **身份与用途由宿主定。** HTTP 入口固定 compose/探索,客户端传 purpose / role / actor 都不看;formal 只在宿主入口 + (execute_formal),复用同一个 publications.judge,发布依据不齐就拒且**不换路**(不降级成探索、不建运行)。 + +数据全是合成的(一个临时 SQLite 库、7 条合成标量指标),不连真实业务库;这些指标不是任何真实业务口径。 +""" +from __future__ import annotations + +import asyncio +import json +import sqlite3 +import uuid +from decimal import Decimal +from typing import Any + +import pytest +from httpx import ASGITransport, AsyncClient +from sqlalchemy import select + +from app.apps import publications +from app.core.artifact_store import graph_hash +from app.db.base import SessionLocal +from app.db.models import DataSource, Run, Workflow, WorkflowVersion +from app.engine.runner import run_manager +from app.ledger import querycore +from app.main import app +from tests import ledger_samples as S +from tests.publication_samples import (add_record, add_version, confirm, make_workflow, publish, report_model) + +#: 这一版口径卡的节点 id(源头口径卡) +CARD = "card" +#: 取数窗口:start(含)/ end(不含) +WINDOW = "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'" +#: 合成库的行(status / region / amount / qty / paid_at) +ROWS = [ + (1, "east", "paid", 100.0, 2, "2026-09-02"), + (2, "east", "paid", 50.0, 1, "2026-09-03"), + (3, "west", "refunded", 30.0, 3, "2026-09-04"), + (4, "west", "paid", 20.0, 4, "2026-09-07"), + (5, "east", "open", 12.5, 5, "2026-09-07"), + (6, "west", "paid", 70.0, 6, "2026-10-02"), + (7, "east", "paid", 5.0, 7, "2026-08-31"), +] +#: 窗口内的期望值(2026-09-01 ≤ paid_at < 2026-10-01,只算 paid) +WINDOW_SUM = 170.0 +WINDOW_UNITS = 7 +EAST_SUM = 150.0 +PEAK = 100.0 + + +def build_db(path) -> None: + db = sqlite3.connect(path) + db.executescript("CREATE TABLE orders (id INTEGER PRIMARY KEY, region TEXT, status TEXT, amount REAL, " + "qty INTEGER, paid_at TEXT);") + db.executemany("INSERT INTO orders VALUES (?, ?, ?, ?, ?, ?)", ROWS) + db.commit() + db.close() + + +async def fresh_source(tmp_path) -> str: + """每个用例一个名字不同的数据源(候选口径按数据源预筛,别的用例的口径不会混进来)。""" + path = tmp_path / "querycore.db" + build_db(path) + S.CURRENT["source"] = f"qc_{uuid.uuid4().hex[:8]}" + await S.set_source(path) + return S.CURRENT["source"] + + +def metrics() -> list[dict[str, Any]]: + """7 条合成标量指标:三条共用 sales 那条 SQL,一条只读 region 那条(带 region 参数),两条共用 shared 那条。""" + return [ + {"id": "gmv", "name": "销售额", "unit": "元", "decimals": 2, "format": "thousands", + "expression": "cell(nodes.sales, 0, 'gmv')"}, + {"id": "units", "name": "件数", "unit": "件", + "expression": "cell(nodes.sales, 0, 'units')"}, + {"id": "label", "name": "合成标签", "unit": "", + "expression": "cell(nodes.sales, 0, 'label')"}, + {"id": "units_exact", "name": "件数放大", "unit": "件", + "expression": "cell(nodes.sales, 0, 'units') * 1000000000000000001"}, + {"id": "region_gmv", "name": "大区销售额", "unit": "元", "decimals": 2, + "expression": "cell(nodes.region, 0, 'gmv')"}, + {"id": "total", "name": "订单总额", "unit": "元", "decimals": 2, + "expression": "cell(nodes.shared, 0, 'total')"}, + {"id": "peak", "name": "最大单笔", "unit": "元", "decimals": 2, + "expression": "cell(nodes.shared, 0, 'peak')"}, + ] + + +#: 除了 region_gmv 之外的全部指标(选它就不用 region 那个参数) +WITHOUT_REGION = [m["id"] for m in metrics() if m["id"] != "region_gmv"] +ALL_METRICS = [m["id"] for m in metrics()] + + +def graph(*, sales_sql: str | None = None, on_missing: str | None = None, table_metric: bool = False) -> dict[str, Any]: + """入口 → 三条取数 → 口径卡 → 报告 → 出口(报告节点只在原图里,探针图不跑它)。 + + on_missing="null" 时口径卡声明「缺输入按空值算」(engine/nodes/metrics 的 on_missing):这时跑完但某个指标没有值, + 正是「跑成功不等于算成了」那一种。""" + card_extra = {"on_missing": on_missing} if on_missing else {} + made = metrics() + if table_metric: + # 声明成表的那一条:这一版只交标量,执行前就拒(不悄悄按第一行给个值) + next(m for m in made if m["id"] == "total")["contract"] = {"shape": "table"} + return S.chain( + S.node("start", "input", fields=[ + {"name": "start", "type": "string", "required": True, "description": "开始日期(含)"}, + {"name": "end", "type": "string", "required": True, "description": "结束日期(不含)"}, + {"name": "region", "type": "string", "required": False, "description": "大区(只有大区口径用)"}, + ]), + S.node("sales", "tool", tool=S.tool(), + args={"sql": sales_sql or f"SELECT SUM(amount) AS gmv, SUM(qty) AS units, '合成标签' AS label " + f"FROM orders WHERE status = 'paid' {WINDOW}"}), + S.node("region", "tool", tool=S.tool(), + args={"sql": "SELECT SUM(amount) AS gmv FROM orders WHERE region = '{{ input.region }}' " + f"AND status = 'paid' {WINDOW}"}), + S.node("shared", "tool", tool=S.tool(), + args={"sql": f"SELECT SUM(amount) AS total, MAX(amount) AS peak FROM orders " + f"WHERE status = 'paid' {WINDOW}"}), + S.node(CARD, "metrics", caliber="合成周销售", caliber_version="v1", metrics=made, **card_extra), + S.node("write", "report", instructions="写周销售"), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.write.text }}"}])) + + +def other_graph() -> dict[str, Any]: + """换个窗口就换了取数(等价于「图上改了东西」),让 v2 有自己的版本行与清单。""" + return graph(sales_sql=f"SELECT SUM(amount) AS gmv, SUM(qty) AS units, '合成标签' AS label " + f"FROM orders WHERE status IN ('paid', 'open') {WINDOW}") + + +@pytest.fixture(autouse=True) +async def engine_up(tmp_path): + await run_manager.setup() + await fresh_source(tmp_path) + yield + await run_manager.shutdown() + + +@pytest.fixture +async def client(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c: + yield c + + +async def run_once(asset: dict, *, metric_ids: list[str], inputs: dict[str, Any] | None = None, **kw): + """走服务入口跑一次(HTTP 之外的那条路),等结果。asset 里带 version 就是点名那一版。""" + calls = dict(kw) + if "version" in asset: + calls.setdefault("version", asset["version"]) + async with SessionLocal() as session: + return await querycore.execute( + session, workflow_id=asset["workflow_id"], card_id=CARD, metric_ids=metric_ids, + inputs=inputs if inputs is not None else {"start": "2026-09-01", "end": "2026-10-01"}, **calls) + + +def values_of(outcome) -> dict[str, Any]: + return {m["id"]: m["value"] for m in outcome.as_dict()["metrics"]} + + +async def settled(run_id: str) -> Run: + """等这次运行收尾(测试收尾不留挂着的任务)。""" + for _ in range(400): + async with SessionLocal() as session: + row = await session.get(Run, run_id) + if row.status in querycore.TERMINAL_RUN_STATUSES: + return row + await asyncio.sleep(0.05) + raise AssertionError(f"运行 {run_id} 没有结束:{row.status}") + + +def no_model(monkeypatch) -> None: + """内部 LLM = 0:任何模型调用都让这次执行炸掉。""" + from app.providers import mock_model + + def boom(self, messages): + raise AssertionError("QueryCore 不该调用模型") + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", boom) + + +# ========================================================================== +# 1、显式版本 / 推荐版:解析一次、当场固定 +# ========================================================================== + + +async def test_explicit_and_recommended_versions_are_pinned_once(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + asset = await add_version(asset, other_graph(), version=2) + await publish(client, asset, version=2) + await publish(client, asset, version=1) # 旧版重新推上去成推荐版 + + follow = await run_once({"workflow_id": asset["workflow_id"]}, metric_ids=["gmv"], + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert follow.ok and follow.version == 1 and follow.explicit_version is False + assert follow.publication["version"] == 1 and follow.publication["manifest"] + # 推荐版那一版是 status='paid':v2 把 open 也算进去,值会不一样(如果解析错了会看出来) + assert follow.metrics[0]["value"] == WINDOW_SUM + + named = await run_once({"workflow_id": asset["workflow_id"], "version": 2}, metric_ids=["gmv"], + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert named.ok and named.version == 2 and named.explicit_version is True + assert named.metrics[0]["value"] == WINDOW_SUM + 12.5 + + +# ========================================================================== +# 2、K08 闭包:选 A 时 B 独有的取数和参数为 0;共享 SQL 保留并声明 +# ========================================================================== + + +async def test_the_unselected_metrics_query_and_parameters_stay_out(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + outcome = await run_once(asset, metric_ids=WITHOUT_REGION, + inputs={"start": "2026-09-01", "end": "2026-10-01", "region": "east"}) + assert outcome.ok + data = outcome.as_dict() + # region 那条查询不进这次范围 + assert [q["node_id"] for q in data["queries"]] == ["sales", "shared"] + assert "region" not in json.dumps(data["queries"]) + # region 这个参数这次不用:不带进执行(照实记在 ignored 里),也不在这次的参数契约里 + assert data["parameters"]["values"] == {"start": "2026-09-01", "end": "2026-10-01"} + assert data["parameters"]["ignored"] == ["region"] + assert [c["name"] for c in data["parameters"]["contract"]] == ["start", "end"] + assert "region" not in json.dumps([q["parameters"] for q in data["parameters"]["queries"]]) + assert set(data["selection"]["metric_ids"]) == set(WITHOUT_REGION) + assert "region_gmv" not in json.dumps(data["queries"]) + for query in data["queries"]: + assert query["found"] and query["executed_hash"] and "executed_sql" not in query + + +async def test_a_shared_sql_stays_and_declares_who_else_it_computes(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + outcome = await run_once(asset, metric_ids=["total"]) + assert outcome.ok and outcome.metrics[0]["value"] == WINDOW_SUM + [query] = outcome.as_dict()["queries"] + assert query["query_id"].endswith(":shared") and query["metric_ids"] == ["total"] + assert query["computes_unselected"] == ["peak"], "共享的那条 SQL 还在算未选中的指标,要如实声明" + # 共享 SQL 里的另一个指标不交回 + assert "peak" not in [m["id"] for m in outcome.as_dict()["metrics"]] + + +async def test_missing_and_unknown_parameters_are_refused_before_any_sql(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.execute(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=["region_gmv"], inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert caught.value.code == "missing_parameter" and caught.value.status_code == 422 + assert caught.value.problems and caught.value.problems[0]["code"] == "missing_parameter" + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as unknown: + await querycore.execute(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=["gmv"], inputs={"start": "2026-09-01", "end": "2026-10-01", + "store": "s1"}) + assert unknown.value.code == querycore.UNKNOWN_INPUT and unknown.value.status_code == 422 + # 两条都在发起运行之前拒:一条 SQL 都没发,也没有留下运行 + async with SessionLocal() as session: + assert (await session.execute(select(Run).where(Run.workflow_id == asset["workflow_id"]))).scalars().all() == [] + + +# ========================================================================== +# 3、零模型、零作者侧编译、零运行期重绑定 +# ========================================================================== + + +async def test_no_model_and_no_author_side_compilation(client, monkeypatch): + no_model(monkeypatch) + + def no_compile(*a, **kw): + raise AssertionError("QueryCore 不做作者侧 SQL 编译") + + monkeypatch.setattr("app.data.rule_compile.compile_rule", no_compile) + asset = await make_workflow(graph=graph()) + await publish(client, asset) + outcome = await run_once(asset, metric_ids=WITHOUT_REGION, + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert outcome.ok + async with SessionLocal() as session: + row = await session.get(Run, outcome.run_id) + kinds = {n["type"] for n in row.graph["nodes"]} + assert kinds <= {"input", "tool", "metrics", "output"}, f"探针图里不该有模型节点:{kinds}" + assert row.origin["service"] == "querycore" and row.origin["purpose"] == querycore.DEFAULT_PURPOSE + assert row.options.get("read_only_data") is True, "这次运行的数据源查询一律只读(READ_ONLY 边界)" + + +async def test_the_executed_sql_is_exactly_the_planned_one(client): + """零运行期重绑定:执行过的语句与这次计划渲染出来的哈希一致、参数输入哈希一致;SQL 正文不外发。""" + asset = await make_workflow(graph=graph()) + await publish(client, asset) + outcome = await run_once(asset, metric_ids=WITHOUT_REGION, + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert outcome.ok + data = outcome.as_dict() + assert all(q["rebound"] is None for q in data["queries"]) + planned = {p["node_id"]: p for p in data["parameters"]["queries"]} + for query in data["queries"]: + plan = planned[query["node_id"]] + assert "executed_sql" not in query, "返回里不给 SQL 正文:要读正文走证据接口" + assert query["executed_hash"] == query["planned_statement_hash"] == plan["statement_hash"] + assert query["parameters"]["inputs_hash"] == plan["inputs_hash"] == query["planned_inputs_hash"] + assert plan["template_hash"] != plan["statement_hash"], "源模板哈希与执行语句哈希不是一回事" + # 这一整段(除快照自带的检查项)里没有 SQL 正文 + shown = json.dumps([{k: v for k, v in q.items() if k not in ("checks", "no_data")} for q in data["queries"]], + ensure_ascii=False).lower() + assert "from orders" not in shown and "paid_at" not in shown and "{{" not in shown + + +# ========================================================================== +# 4、类型与时区:decimal / 大整数不转 float,带时区的取值原样进语句 +# ========================================================================== + + +def test_typed_values_never_coerce_decimal_or_big_integers(): + assert querycore.typed(Decimal("123.456")) == "decimal" + assert querycore.typed(2 ** 80) == "integer" + assert querycore.typed("123.456") == "decimal" + assert querycore.typed("000012") == "string" + assert querycore.typed(True) == "boolean" + assert querycore.typed(None) == "null" + assert querycore.typed(1.5) == "number" + + +def test_the_projection_keeps_decimal_and_big_integers_exact(): + """Decimal 与超长整数过投影时一个位数都不丢:Decimal 交回精确文本并标成 decimal(接口把 Decimal 编码成 float 会 + 丢精度),大整数原样是整数。整份投影还要能直接 json.dumps(不会有 Decimal 漏过去)。""" + base = {"id": "d", "name": "十进制", "unit": "元", "status": "ok", "rendered": "123.456", "decimals": 3} + decimal = querycore._typed_metric({**base, "value": Decimal("123.456")}, None) + assert decimal["value"] == "123.456" and decimal["value_type"] == "decimal" + assert not isinstance(decimal["value"], float) + big = querycore._typed_metric({**base, "value": 10 ** 25}, None) + assert big["value"] == 10 ** 25 and big["value_type"] == "integer" and isinstance(big["value"], int) + assert json.dumps([decimal, big], ensure_ascii=False) + assert querycore.exact(Decimal("0.10")) == "0.10" and querycore.exact(2 ** 70) == 2 ** 70 + + +async def test_values_keep_their_exact_type_and_timezone(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + tz_end = "2026-10-01T00:00:00+08:00" + outcome = await run_once(asset, metric_ids=WITHOUT_REGION, inputs={"start": "2026-09-01", "end": tz_end}) + assert outcome.ok + data = outcome.as_dict() + by_id = {m["id"]: m for m in data["metrics"]} + # 大整数:精确的整数,不是 float(不无条件转 float) + assert by_id["units_exact"]["value"] == WINDOW_UNITS * 1000000000000000001 + assert by_id["units_exact"]["value_type"] == "integer" + assert isinstance(by_id["units_exact"]["value"], int) + # 整数与小数各自标成自己的类型;非数字文本照旧是文本 + assert by_id["units"]["value_type"] == "integer" and isinstance(by_id["units"]["value"], int) + assert by_id["gmv"]["value_type"] == "number" and by_id["label"]["value"] == "合成标签" + assert by_id["label"]["value_type"] == "string" + # 带时区的取值原样进语句、原样回交(不 shift、不重解释):执行过的语句与计划一致(见上面那条), + # 参数那一份里记的就是原样的字符串 + assert data["parameters"]["values"]["end"] == tz_end + assert [p["parameters"] for p in data["parameters"]["queries"]][0][0]["name"] == "start" + assert data["data"]["window"]["end"] == tz_end and data["data"]["as_of"] + + +# ========================================================================== +# 5、伪造版本 / 过期清单 / 不兼容编译器 / 老资产 +# ========================================================================== + + +async def test_a_forged_version_is_refused(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.execute(session, workflow_id=asset["workflow_id"], card_id=CARD, metric_ids=["gmv"], + version=99, inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert caught.value.code == querycore.VERSION_MISSING and caught.value.status_code == 404 + async with SessionLocal() as session: + assert (await session.execute(select(Run).where(Run.workflow_id == asset["workflow_id"]))).scalars().all() == [] + + +async def test_a_card_outside_the_version_and_an_empty_selection_are_refused(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as missing: + await querycore.execute(session, workflow_id=asset["workflow_id"], card_id="nope", metric_ids=["gmv"], + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + with pytest.raises(querycore.QueryCoreRefused) as empty: + await querycore.execute(session, workflow_id=asset["workflow_id"], card_id=CARD, metric_ids=[], + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert missing.value.code == querycore.CARD_MISSING and missing.value.status_code == 409 + assert empty.value.code == querycore.SELECTION_REFUSED and empty.value.status_code == 422 + async with SessionLocal() as session: + assert (await session.execute(select(Run).where(Run.workflow_id == asset["workflow_id"]))).scalars().all() == [] + + +async def test_a_table_shaped_metric_is_refused_in_this_version(client): + """首版只交标量:声明成表的指标在发 SQL 之前就拒,不悄悄按第一行给个值。""" + asset = await make_workflow(graph=graph(table_metric=True)) + await publish(client, asset) + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.execute(session, workflow_id=asset["workflow_id"], card_id=CARD, metric_ids=["total"], + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert caught.value.code == querycore.OUTPUT_UNSUPPORTED and caught.value.status_code == 422 + async with SessionLocal() as session: + assert (await session.execute(select(Run).where(Run.workflow_id == asset["workflow_id"]))).scalars().all() == [] + + +async def test_a_manifest_for_another_graph_is_refused(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + async with SessionLocal() as session: + row = (await session.execute(select(WorkflowVersion).where( + WorkflowVersion.workflow_id == asset["workflow_id"], WorkflowVersion.version == 1))).scalar_one() + row.graph = other_graph() # 同一版号、换了图 + await session.commit() + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.execute(session, workflow_id=asset["workflow_id"], card_id=CARD, metric_ids=["gmv"], + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert caught.value.code == publications.BASIS_MISMATCH + assert caught.value.problems and "图指纹" in caught.value.problems[0]["message"] + + +async def test_an_incompatible_compiler_is_refused_without_reinterpreting(client, monkeypatch): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + real = publications.compiler_versions + monkeypatch.setattr(publications, "compiler_versions", + lambda: {**real(), "binding": {"binder": "controlled_template", "version": 99}}) + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.execute(session, workflow_id=asset["workflow_id"], card_id=CARD, metric_ids=["gmv"], + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert caught.value.code == querycore.INCOMPATIBLE + assert caught.value.problems and caught.value.problems[0]["key"] == "binding" + assert "不按新规则重解释旧发布" in caught.value.message + + +def test_the_compiler_seam_rejects_an_old_manifest_without_a_resolver(): + """加 resolver 这一项之前物化的清单(缺 resolver):认不出它按哪一版闭包解析,明确拒。""" + content = {"format": publications.FORMAT, "compiler": {k: v for k, v in publications.compiler_versions().items() + if k != "resolver"}} + problems = publications.compiler_problems(content) + assert [p["key"] for p in problems] == ["resolver"] and problems[0]["code"] == publications.COMPILER_MISMATCH + # 现在这一套自己写出来的清单一项都不差;没有 compiler 这一段的清单另给一个码 + assert publications.compiler_problems({"compiler": publications.compiler_versions()}) == [] + assert publications.compiler_problems({"compiler": None})[0]["code"] == publications.COMPILER_MISSING + # 多出一项现在认不出的约定一样算不兼容(不静默放行) + extra = {**publications.compiler_versions(), "future_thing": 1} + assert [p["key"] for p in publications.compiler_problems({"compiler": extra})] == ["future_thing"] + + +async def test_a_legacy_asset_without_a_manifest_is_refused(client): + """老资产(这一版没有发布事件):QueryCore 明确拒;旧 trial 路径一个字不动。""" + workflow_id = await S.publish(graph=graph()) # 直接写库(老写法,不经过发布入口) + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.execute(session, workflow_id=workflow_id, card_id=CARD, metric_ids=["gmv"], + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert caught.value.code == querycore.MANIFEST_REQUIRED and caught.value.status_code == 409 + # 老试跑照旧能跑(试跑只认这一版发布过) + res = await client.post(f"/api/ledger/calibers/{workflow_id}/1/{CARD}/trial", + json={"inputs": {"start": "2026-09-01", "end": "2026-10-01", "region": "east"}}) + assert res.status_code == 200, res.text + assert res.json()["status"] in ("succeeded", "running", "failed") + + +# ========================================================================== +# 6、formal:只在宿主入口、复用同一个 judge、发布依据不齐不换路 +# ========================================================================== + + +async def test_the_formal_host_entry_reuses_the_judge_and_never_switches_path(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) # 有清单、没有验证记录与审阅 + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.execute_formal(session, workflow_id=asset["workflow_id"], card_id=CARD, metric_ids=["gmv"], + inputs={"start": "2026-09-01", "end": "2026-10-01"}, actor="宿主") + assert caught.value.code == publications.RECORD_MISSING, "formal 用的是 publications.judge 的原码" + assert caught.value.status_code == 409 + # 不换路:不降级成探索执行,也不留下任何运行 + async with SessionLocal() as session: + assert (await session.execute(select(Run).where(Run.workflow_id == asset["workflow_id"]))).scalars().all() == [] + + record_id = await add_record(asset) + await confirm(asset, record_id) + await publish(client, asset) # 依据齐了之后重新发布 + async with SessionLocal() as session: + outcome = await querycore.execute_formal(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=["gmv"], + inputs={"start": "2026-09-01", "end": "2026-10-01"}, actor="宿主") + assert outcome.ok and outcome.purpose == publications.PURPOSE_FORMAL + assert outcome.publication["identity"] == publications.PROVEN + assert outcome.publication["requires_proof"] is True + async with SessionLocal() as session: + run = await session.get(Run, outcome.run_id) + assert run.origin["purpose"] == publications.PURPOSE_FORMAL + assert run.origin["identity"] == publications.PROVEN and run.started_by == "宿主" + + +async def test_the_interactive_entry_is_exploratory_and_cannot_be_escalated(client): + """默认交互入口是 compose/探索:客户端传 purpose / role / actor 一律不看,也拿不到正式身份。""" + asset = await make_workflow(graph=graph()) + await publish(client, asset) # 有清单、没有验证记录(formal 会拒) + res = await client.post("/api/ledger/querycore", json={ + "workflow_id": asset["workflow_id"], "card_id": CARD, "metric_ids": ["gmv"], + "inputs": {"start": "2026-09-01", "end": "2026-10-01"}, + "purpose": "formal", "role": "admin", "actor": "冒充的人", "version": 1}) + assert res.status_code == 200, res.text + body = res.json() + assert body["ok"] and body["purpose"] == publications.PURPOSE_COMPOSE + async with SessionLocal() as session: + run = await session.get(Run, body["run_id"]) + assert run.origin["purpose"] == publications.PURPOSE_COMPOSE, "用途由宿主常量定,客户端改不了" + assert run.origin["identity"] == publications.UNPROVEN and run.run_class == "exploratory" + assert run.started_by is None, "认证主体来自服务端,请求体里的 actor 不看" + + +async def test_a_role_refusal_does_not_switch_path(client): + """权限失败不换路:这个入口只给搭建者及以上(路由级依赖)。使用者被拒时不降级、不换别的路、也不留下运行。""" + from tests.fakes import auth_env + + asset = await make_workflow(graph=graph()) + await publish(client, asset) + try: + await auth_env.turn_on_local() + await auth_env.make_user("uma", "user") + uma = await auth_env.login("uma") + res = await uma.post("/api/ledger/querycore", json={"workflow_id": asset["workflow_id"], "card_id": CARD, + "metric_ids": ["gmv"], + "inputs": {"start": "2026-09-01", "end": "2026-10-01"}}) + assert res.status_code == 403 and res.json()["code"] == "role_required" + finally: + await auth_env.reset() + async with SessionLocal() as session: + assert (await session.execute(select(Run).where(Run.workflow_id == asset["workflow_id"]))).scalars().all() == [] + + +# ========================================================================== +# 7、超时:回 running + run_id,绝不冒充成功 +# ========================================================================== + + +async def test_a_timeout_returns_running_and_never_success(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + outcome = await run_once(asset, metric_ids=["gmv"], timeout_s=0.0, + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert outcome.status == "running" and outcome.ok is False and outcome.run_id + assert [p["code"] for p in outcome.problems] == [querycore.TIMEOUT] + assert outcome.metrics == () and outcome.queries == () + assert outcome.quality["execution"] == "running" and outcome.quality["status"] != "pass" + # 运行照旧跑完(超时只影响这次接口怎么回,不影响运行本身) + assert (await settled(outcome.run_id)).status == "succeeded" + # HTTP 那条路同样:回 running + run_id,绝不成功 + res = await client.post("/api/ledger/querycore", json={ + "workflow_id": asset["workflow_id"], "card_id": CARD, "metric_ids": ["gmv"], + "inputs": {"start": "2026-09-01", "end": "2026-10-01"}, "budget": {"timeout_s": 0.0}}) + assert res.status_code == 200 and res.json()["status"] == "running" and res.json()["ok"] is False + assert res.json()["problems"][0]["code"] == querycore.TIMEOUT + + +# ========================================================================== +# 8、空结果 / 只有一部分指标有值:都不是成功 +# ========================================================================== + + +async def test_an_empty_window_is_not_a_success(client): + """窗口里没有数据(SUM 全空):这次执行明确失败,ok=False,一件指标都不交回——空结果不冒充成功。""" + asset = await make_workflow(graph=graph()) + await publish(client, asset) + outcome = await run_once(asset, metric_ids=WITHOUT_REGION, + inputs={"start": "2030-01-01", "end": "2030-02-01"}) + assert outcome.status == "failed" and outcome.ok is False + assert [p["code"] for p in outcome.problems] == [querycore.EXECUTION] + assert outcome.metrics == () and outcome.queries == () + assert outcome.quality["status"] == "fail" and outcome.quality["execution"] == "failed" + + +async def test_a_metric_without_a_value_is_not_a_success(client): + """声明了「缺输入按空值算」的口径:跑完了,但指标没有值——跑成功不等于算成了,照实 ok=False。""" + asset = await make_workflow(graph=graph(on_missing="null")) + await publish(client, asset) + outcome = await run_once(asset, metric_ids=WITHOUT_REGION, + inputs={"start": "2030-01-01", "end": "2030-02-01"}) + assert outcome.status == "succeeded" and outcome.ok is False + codes = [p["code"] for p in outcome.problems] + # 6 条里 5 条没有值(聚合全空);label 那一格是 SELECT 里的字面量,照常有一行,所以它有值 + no_value = [m["id"] for m in outcome.metrics if m["value"] is None] + assert codes.count(querycore.METRIC_NO_VALUE) == len(no_value) == len(WITHOUT_REGION) - 1 + assert {m["id"]: m["value"] for m in outcome.metrics}["label"] == "合成标签" + assert outcome.quality["status"] == "fail" + + +async def test_a_budget_smaller_than_the_plan_is_refused(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.execute(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=WITHOUT_REGION, budget={"max_queries": 1}, + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert caught.value.code == querycore.BUDGET_REFUSED and caught.value.status_code == 429 + async with SessionLocal() as session: + assert (await session.execute(select(Run).where(Run.workflow_id == asset["workflow_id"]))).scalars().all() == [] + + +async def test_a_masked_metric_is_not_handed_out_as_a_value(client, tmp_path): + """数据源设了遮罩列:被遮的指标不给值、ok=False——不把遮罩值当结果交出(同试跑与证据接口的分寸)。""" + asset = await make_workflow(graph=graph()) + await publish(client, asset) + await S.set_source(tmp_path / "querycore.db", options={"mask_columns": ["gmv"]}) + outcome = await run_once(asset, metric_ids=WITHOUT_REGION, + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + by_id = {m["id"]: m for m in outcome.as_dict()["metrics"]} + assert by_id["gmv"].get("masked") is True and by_id["gmv"]["value"] is None + assert outcome.ok is False and querycore.METRIC_MASKED in [p["code"] for p in outcome.problems] + + +# ========================================================================== +# 9、证据关联:每条查询都指得到工件、来源与 attempt;指标出自这次运行的封存证据 +# ========================================================================== + + +async def test_every_query_points_at_its_artifact_and_source(client): + asset = await make_workflow(graph=graph()) + await publish(client, asset) + outcome = await run_once(asset, metric_ids=WITHOUT_REGION, + inputs={"start": "2026-09-01", "end": "2026-10-01"}) + assert outcome.ok + from app.core.artifact_store import load + + for query in outcome.as_dict()["queries"]: + assert query["found"] is True and query["artifact"] + snap = load(query["artifact"]) + assert snap["sql"] and query["executed_hash"] and "executed_sql" not in query + assert query["data_source"] == S.CURRENT["source"] + assert query["attempt"] is not None and query["attempt"] >= 1 + assert query["columns"] and query["row_count"] == 1 and query["truncated"] is False + assert query["source"]["workflow_id"] == asset["workflow_id"] and query["source"]["version"] == 1 + assert query["source"]["node_id"] in ("sales", "shared") + assert query["tables"] == ["orders"] + assert {m["id"] for m in outcome.metrics} == set(WITHOUT_REGION) + assert outcome.data["sources"] == [S.CURRENT["source"]] and outcome.data["tables"] == ["orders"] + assert outcome.data["read"] is True and outcome.quality["status"] in ("pass", "unknown") + + +async def test_all_seven_synthetic_scalars_come_back_typed(client): + """一次全覆盖:7 条合成标量指标都回来(金额/件数/文本/放大/大区/总额/最大单笔),不是真实业务指标。""" + asset = await make_workflow(graph=graph()) + await publish(client, asset) + outcome = await run_once(asset, metric_ids=ALL_METRICS, + inputs={"start": "2026-09-01", "end": "2026-10-01", "region": "east"}) + assert outcome.ok + got = values_of(outcome) + assert got["gmv"] == WINDOW_SUM and got["units"] == WINDOW_UNITS + assert got["region_gmv"] == EAST_SUM and got["total"] == WINDOW_SUM and got["peak"] == PEAK + assert got["label"] == "合成标签" + assert got["units_exact"] == WINDOW_UNITS * 1000000000000000001 + assert len(outcome.metrics) == 7 + # 大区和总额两条不同的查询各留下自己的工件与来源 + assert {q["node_id"] for q in outcome.as_dict()["queries"]} == {"sales", "region", "shared"} + assert len({q["artifact"] for q in outcome.as_dict()["queries"]}) == 3 diff --git a/backend/tests/test_querycore_perf.py b/backend/tests/test_querycore_perf.py new file mode 100644 index 00000000..47f47575 --- /dev/null +++ b/backend/tests/test_querycore_perf.py @@ -0,0 +1,588 @@ +"""K13:固定执行的测量与受控性能基线(app/ledger/querycore.py 的 measurement、engine/runner 的 usage.queue_ms)。 + +这份文件盯住两件事: + +1. **测量本身是真的**(默认每次都跑):一次固定执行交回的 measurement 把阶段耗时(发布/定位、闭包/计划、参数、排队、 + 数据库、证据、总耗时)、计数(计划与**真发出去**的 SQL 条数、内部模型调用数、交回的查询条数与截断条数、问题/错误/ + 超时)连同 trace / run / query 身份一起记下来。各阶段加得起来;量不到的字段是 None,不填 0 冒充;SQL 条数对着真的 + 执行次数;LLM 恒为 0;超时回 running 且**不冒充成功**;排队(usage.queue_ms)绝不拿等人审批的 wait_ms 顶上。 +2. **基线是 opt-in 的**(`AGENTLAB_QUERYCORE_PERF=1` 才跑):同一份代码、同一份数据快照、同一组参数、同一台机器、 + 同一份预算,冷启动(先清掉进程内缓存的那一次)与热执行分开,各档至少 100 次,原始样本 + P50/P95 + 错误率;跑并发 1 + 与并发 4 两档(名额上限 1 与 2,4 那一档一半在排队,用来验证 queue_ms)。**失败样本不剔除**:都留在样本里、算进错误率。 + +数据全是合成的(一个临时 SQLite 库、7 条合成标量指标),不连真实业务库;样本只写临时目录。 + +**没有生产负载,这份基线推不出生产的 P50/P95**——它只说明这套代码在这台机器、这份数据、这组参数、这份预算下的样子。 +""" +from __future__ import annotations + +import asyncio +import contextlib +import hashlib +import json +import math +import os +import platform +import tempfile +import time +import uuid +from pathlib import Path +from typing import Any + +import pytest +from httpx import ASGITransport, AsyncClient + +from app.db.base import SessionLocal +from app.db.models import Run +from app.engine.runner import run_manager +from app.ledger import querycore +from app.main import app +from tests import ledger_samples as S +from tests.fixtures.sources import drop_source +from tests.publication_samples import make_workflow, publish + +#: 口径卡的节点 id +CARD = "card" +#: 取数窗口:start(含)/ end(不含) +WINDOW = "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'" +#: 这次的入口取值(每个样本都一样:同一组参数) +INPUTS = {"start": "2026-09-01", "end": "2026-09-08"} +#: 窗口内的期望值(合成店铺库:三单、两个大区、两家门店) +WINDOW_GMV = 170.5 +WINDOW_ORDERS = 3 +#: 合成库上的 7 条标量指标(落在 3 条取数 SQL 上) +METRIC_IDS = ["gmv", "orders", "peak", "buyers", "gmv_cents", "region_gmv", "store_count"] +#: 闭包要执行几条查询:三条取数各一条 +QUERIES = 3 + + +def metrics() -> list[dict[str, Any]]: + """7 条合成标量指标:sales 那条 SQL 出 4 个(gmv_cents 与之共用),另两条取数各出 1 个。""" + return [ + {"id": "gmv", "name": "销售额", "unit": "元", "decimals": 2, "expression": "cell(nodes.sales, 0, 'gmv')"}, + {"id": "orders", "name": "订单数", "unit": "单", "expression": "cell(nodes.sales, 0, 'orders')"}, + {"id": "peak", "name": "最大单笔", "unit": "元", "decimals": 2, "expression": "cell(nodes.sales, 0, 'peak')"}, + {"id": "buyers", "name": "买家数", "unit": "人", "expression": "cell(nodes.sales, 0, 'buyers')"}, + {"id": "gmv_cents", "name": "销售额(分)", "unit": "分", "decimals": 0, + "expression": "cell(nodes.sales, 0, 'gmv') * 100"}, + {"id": "region_gmv", "name": "大区销售额", "unit": "元", "decimals": 2, + "expression": "cell(nodes.region, 0, 'region_gmv')"}, + {"id": "store_count", "name": "门店数", "unit": "家", "expression": "cell(nodes.stores, 0, 'stores')"}, + ] + + +def perf_graph() -> dict[str, Any]: + """入口 → 三条取数 → 口径卡(7 条指标)→ 出口。取数节点自己的 SQL 不点入口参数以外的任何东西。""" + return S.chain( + S.node("start", "input", fields=[{"name": "start", "type": "string", "required": True}, + {"name": "end", "type": "string", "required": True}]), + S.node("sales", "tool", tool=S.tool(), + args={"sql": "SELECT SUM(amount) AS gmv, COUNT(*) AS orders, MAX(amount) AS peak, " + f"COUNT(DISTINCT phone) AS buyers FROM orders WHERE status = 'paid' {WINDOW}"}), + S.node("region", "tool", tool=S.tool(), + args={"sql": "SELECT region, SUM(amount) AS region_gmv FROM orders " + f"WHERE status = 'paid' {WINDOW} GROUP BY region ORDER BY region"}), + S.node("stores", "tool", tool=S.tool(), args={"sql": "SELECT COUNT(*) AS stores FROM stores"}), + S.node(CARD, "metrics", caliber="周销售", caliber_version="v1", metrics=metrics()), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.sales }}"}])) + + +def clipping_graph() -> dict[str, Any]: + """一条取数按大区分组、只留一行:结果被截短(truncated),测量里要数得出来。""" + return S.chain( + S.node("start", "input", fields=[{"name": "start", "type": "string", "required": True}, + {"name": "end", "type": "string", "required": True}]), + S.node("sales", "tool", tool=S.tool(), + args={"sql": "SELECT region, SUM(amount) AS gmv FROM orders " + f"WHERE status = 'paid' {WINDOW} GROUP BY region ORDER BY region", "limit": 1}), + S.node(CARD, "metrics", caliber="周销售", caliber_version="v1", metrics=[ + {"id": "gmv", "name": "销售额", "unit": "元", "decimals": 2, "expression": "cell(nodes.sales, 0, 'gmv')"}]), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.sales }}"}])) + + +async def make_asset(tmp_path, client, build) -> dict[str, Any]: + """建一份已发布的合成口径:临时 SQLite 库(合成店铺库)+ 已发布版本 + 发布清单。数据只写临时目录。 + + build() 在数据源定下来**之后**才调用:图里的工具名带着这一次的源名。""" + path = tmp_path / f"perf_{uuid.uuid4().hex[:6]}.db" + S.build_shop(path) + S.CURRENT["source"] = f"perf_{uuid.uuid4().hex[:8]}" + source_id = await S.set_source(path) + made = await make_workflow(graph=build()) + await publish(client, made) + return {**made, "source_id": source_id} + + +@pytest.fixture(autouse=True) +async def engine_up(): + await run_manager.setup() + yield + await run_manager.shutdown() + + +@pytest.fixture +async def client(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c: + yield c + + +@pytest.fixture +async def asset(tmp_path, client): + """这份文件大部分用例用的那份口径(7 条指标、3 条取数)。""" + made = await make_asset(tmp_path, client, perf_graph) + yield made + await drop_source(made["source_id"]) + + +async def execute_once(asset: dict, *, trace: str | None = None, timeout_s: float | None = None, + metric_ids: list[str] | None = None) -> Any: + """走服务入口跑一次(同一组参数、同一份数据快照),等结果。""" + async with SessionLocal() as session: + return await querycore.execute(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=list(METRIC_IDS if metric_ids is None else metric_ids), + inputs=dict(INPUTS), trace=trace, timeout_s=timeout_s) + + +async def run_row(run_id: str) -> Run | None: + async with SessionLocal() as session: + return await session.get(Run, run_id) + + +def no_model(monkeypatch) -> None: + """内部 LLM = 0:任何模型调用都让这次执行炸掉。""" + from app.providers import mock_model + + def boom(self, messages): + raise AssertionError("QueryCore 不该调用模型") + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", boom) + + +def count_sql_calls(monkeypatch) -> dict[str, int]: + """独立地数这次真正发出去几条 SQL:包住调用工具节点的执行器,只数这次那个数据源工具被调了几次。""" + from app.engine import compiler + from app.engine.schema import NodeType + + original = compiler.RUNNERS[NodeType.TOOL] + seen = {"calls": 0} + + async def runner(state, ctx): + if str(getattr(ctx, "config", {}).get("tool") or "") == S.tool(): + seen["calls"] += 1 + return await original(state, ctx) + + monkeypatch.setitem(compiler.RUNNERS, NodeType.TOOL, runner) + return seen + + +def slow_tools(monkeypatch, seconds: float) -> None: + """把取数拖慢:让「还在跑」那一段足够长,超时用例不靠机器快不快碰运气。""" + from app.engine import compiler + from app.engine.schema import NodeType + + original = compiler.RUNNERS[NodeType.TOOL] + + async def runner(state, ctx): + if str(getattr(ctx, "config", {}).get("tool") or "") == S.tool(): + await asyncio.sleep(seconds) + return await original(state, ctx) + + monkeypatch.setitem(compiler.RUNNERS, NodeType.TOOL, runner) + + +def limit_slots(monkeypatch, limit: int) -> None: + """把并发名额的全站上限定成 limit:名额本身走真实那一套(app/cluster/slots),只把「现在生效的设置」这一个入口 + 换掉。**不往库里写设置**——写下去这一条用例跑完也不恢复,后面的用例会跟着排成单名额,而父运行调用口径查询时 + 父子两个运行同时要名额,单名额就等成死锁。""" + from app.cluster import slots + + value = slots.values({"max_total": limit, + "classes": {k: {"limit": limit, "priority": 40 - i} for i, k in enumerate(slots.CLASSES)}}) + + async def fixed(*, fresh: bool = False): # noqa: ARG001 - 和真 policy 同一个签名 + return value + + monkeypatch.setattr(slots, "policy", fixed) + + +# ========================================================================== +# 1、测量本身:阶段加得起来、字段不虚构、身份留得住 +# ========================================================================== + + +def test_an_old_run_never_gets_a_queue_time_invented_for_it(): + """加 queue_ms 这一项之前跑完的运行记录里没有它:读的一方要按「没量过」处理(None),绝不拿 wait_ms 冒充排队。""" + class Old: + usage = {"duration_ms": 12, "wall_ms": 12, "active_ms": 12, "wait_ms": 900} + + class Fresh: + usage = {"duration_ms": 12, "wall_ms": 12, "active_ms": 12, "wait_ms": 0, "queue_ms": 7} + + class Bogus: + usage = {"queue_ms": "7"} + + assert querycore._queue_of(Old()) is None, "老运行没有这一项:不许拿那 900ms 的 wait_ms 顶上" + assert querycore._queue_of(Fresh()) == 7 + assert querycore._queue_of(Bogus()) is None, "存坏了的按没量到算" + assert querycore._queue_of(None) is None + + +async def test_the_measurement_locates_every_stage_and_adds_up(asset): + """一次跑得成、数也对的执行:阶段加得起来,计数与身份都对得上,排队按运行记录上那一项来。""" + outcome = await execute_once(asset, trace="perf-locate") + assert outcome.ok, outcome.problems + measured = outcome.as_dict()["measurement"] + phases, counts, ids = measured["phases"], measured["counts"], measured["ids"] + + assert set(phases) == set(querycore.PHASES) + for name, value in phases.items(): + assert isinstance(value, int) and value >= 0, (name, value) + # 跑的还是那份合成数据、那组参数:窗口里的期望值对得上(不是「跑通了但算的是别的东西」) + values = {m["id"]: m["value"] for m in outcome.metrics} + assert values["gmv"] == WINDOW_GMV and values["orders"] == WINDOW_ORDERS + # 首尾相接的五段加起来就是总耗时,中间只差测量自身那几十微秒 + disjoint = sum(phases[name] for name in ("locate_ms", "closure_ms", "params_ms", "run_ms", "evidence_ms")) + assert 0 <= phases["total_ms"] - disjoint <= 60, phases + # queue / database 是 run 里面的两段:各出自己的出处,不重复计时 + assert 0 <= phases["queue_ms"] <= phases["run_ms"], phases + assert 0 <= phases["database_ms"] <= phases["run_ms"], phases + assert phases["database_ms"] > 0, "真查了三条 SQL,取数那一段不该是 0" + + # 排队那一项就是运行记录上的 queue_ms(不是等人审批的 wait_ms) + row = await run_row(outcome.run_id) + assert row is not None and row.status == "succeeded" + assert phases["queue_ms"] == row.usage["queue_ms"] + assert row.usage["wait_ms"] == 0, "这次没人审批" + + # 计数:计划 3 条、真发出去 3 条、模型 0 次、交回 3 条、一条都没截断、没有错也没有超时 + assert counts == {"planned_queries": QUERIES, "executed_sql": QUERIES, "llm_calls": 0, + "returned_queries": QUERIES, "truncated_queries": 0, + "problems": 0, "errors": 0, "timeouts": 0} + + # 身份:run / trace / query 都对得上,按其中任何一个都能找回来 + assert ids["run_id"] == outcome.run_id + assert ids["trace"] == "perf-locate" + assert ids["workflow_id"] == asset["workflow_id"] and ids["card_id"] == CARD and ids["version"] == 1 + assert len(ids["query_ids"]) == QUERIES and len(ids["execution_ids"]) == QUERIES + assert ids["execution_ids"] == [q["execution_id"] for q in outcome.as_dict()["queries"]] + assert set(outcome.as_dict()["data"]["sources"]) == {S.CURRENT["source"]} + + +async def test_the_http_entry_hands_the_measurement_out(asset, client): + """接口这一层也交回测量:调用方拿这一份就能按 run_id / trace / query_ids 定位回去。""" + res = await client.post("/api/ledger/querycore", json={ + "workflow_id": asset["workflow_id"], "card_id": CARD, "metric_ids": list(METRIC_IDS), + "inputs": dict(INPUTS), "trace": "perf-http"}) + assert res.status_code == 200, res.text + body = res.json() + measured = body["measurement"] + assert measured["ids"]["run_id"] == body["run_id"] and measured["ids"]["trace"] == "perf-http" + assert measured["counts"]["executed_sql"] == QUERIES and measured["counts"]["llm_calls"] == 0 + assert measured["phases"]["total_ms"] >= measured["phases"]["run_ms"] + assert len(measured["ids"]["query_ids"]) == QUERIES + + +async def test_the_sql_count_is_the_number_of_statements_actually_sent(asset, monkeypatch): + """SQL 条数对着真的执行次数(独立数一遍),内部模型调用恒为 0。""" + no_model(monkeypatch) + seen = count_sql_calls(monkeypatch) + outcome = await execute_once(asset) + assert outcome.ok, outcome.problems + measured = outcome.as_dict()["measurement"] + assert seen["calls"] == QUERIES, "三次取数各发一条 SQL" + assert measured["counts"]["executed_sql"] == seen["calls"] == QUERIES + assert measured["counts"]["planned_queries"] == QUERIES + assert measured["counts"]["llm_calls"] == 0 + # 取数那一段也确实量到了:三条 SQL 各自都记了执行时长 + assert measured["phases"]["database_ms"] > 0 + + +async def test_a_timeout_stays_running_and_never_fills_in_what_it_could_not_measure(asset, monkeypatch): + """超时:状态是 running、ok=False,**没量到的字段是 None**——不拿计划条数或 0 冒充已执行。""" + slow_tools(monkeypatch, 0.4) + started = time.perf_counter() + outcome = await execute_once(asset, timeout_s=0.0) + assert outcome.status == "running" and outcome.ok is False + assert [p["code"] for p in outcome.problems] == [querycore.TIMEOUT] + assert outcome.run_id, "没收尾也要把 run_id 交回,让人能去看" + assert time.perf_counter() - started < 0.4, "到点就返回,不等它跑完" + + measured = outcome.as_dict()["measurement"] + phases, counts, ids = measured["phases"], measured["counts"], measured["ids"] + # 量得到的照记(这次是刚刚才发起的),量不到的照实空着 + assert isinstance(phases["total_ms"], int) and isinstance(phases["run_ms"], int) + assert phases["database_ms"] is None, "没跑完没有执行证据:数据库那一截是 None,不是 0" + assert phases["queue_ms"] is None, "还没收尾,运行记录上还没有排队这一项" + assert counts["timeouts"] == 1 and counts["errors"] == 0 + assert counts["planned_queries"] == QUERIES + assert counts["executed_sql"] is None and counts["llm_calls"] is None + assert counts["returned_queries"] is None and counts["truncated_queries"] is None + assert ids["run_id"] == outcome.run_id and len(ids["query_ids"]) == QUERIES + row = await run_row(outcome.run_id) + assert row is not None and row.status == "running", "超时那一刻运行还在跑" + + +async def test_the_truncated_count_matches_the_queries_that_were_clipped(tmp_path, client): + """交回几条、被截几条,数得出来:结果被截短时台账标它、测量里也数到它。""" + made = await make_asset(tmp_path, client, clipping_graph) + try: + outcome = await execute_once(made, metric_ids=["gmv"]) + finally: + await drop_source(made["source_id"]) + assert outcome.ok, outcome.problems + [query] = outcome.as_dict()["queries"] + assert query["truncated"] is True and query["row_count"] == 1 + counts = outcome.as_dict()["measurement"]["counts"] + assert counts["planned_queries"] == counts["executed_sql"] == 1 + assert counts["returned_queries"] == 1 and counts["truncated_queries"] == 1 + + +async def test_queue_never_takes_the_place_of_waiting_on_a_person(asset, monkeypatch): + """排队(等并发名额)与等人审批是两回事:谁也不冒充谁。 + + 一:没人和它抢名额时,queue_ms 只有「要名额到拿到名额」那一下的开销,而 wait_ms 是等人那 0.5 秒。 + 二:名额确实被别人占着时,queue_ms 记的就是等名额的那一段,wait_ms 仍然是 0。 + """ + # 一、等人:图停在审批上 0.5 秒 + gate_graph = S.chain( + S.node("start", "input"), + S.node("gate", "human", mode="approve", title="看一眼"), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.gate.approved }}"}]), + ) + run = await run_manager.start(graph=gate_graph, input_payload={}) + for _ in range(200): + if (await run_row(run.id)).status == "interrupted": + break + await asyncio.sleep(0.02) + await asyncio.sleep(0.5) + await run_manager.resume(run.id, {"approved": True}) + for _ in range(400): + row = await run_row(run.id) + if row.status in querycore.TERMINAL_RUN_STATUSES: + break + await asyncio.sleep(0.02) + assert row.status == "succeeded", row.error + assert row.usage["wait_ms"] >= 400, row.usage + assert row.usage["queue_ms"] < 200, "排队不能把等人那 0.5 秒算进去" + + # 二、等名额:唯一的名额被别人占着,0.3 秒后才放 + limit_slots(monkeypatch, 1) + from app.cluster import slots + + hog = slots.hold("perf-hog", "chat") + await hog.__aenter__() + + async def release() -> None: + await asyncio.sleep(0.3) + await hog.__aexit__(None, None, None) + + releaser = asyncio.create_task(release()) + try: + outcome = await execute_once(asset, trace="perf-queue") + finally: + # 用例中途出错也要把名额放掉:占着唯一的名额会拖住后面每一个用例 + if not releaser.done(): + releaser.cancel() + with contextlib.suppress(Exception): + await hog.__aexit__(None, None, None) + + assert outcome.ok, outcome.problems + phases = outcome.as_dict()["measurement"]["phases"] + assert phases["queue_ms"] >= 250, phases + row = await run_row(outcome.run_id) + assert row.usage["queue_ms"] == phases["queue_ms"] and row.usage["wait_ms"] == 0 + + +# ========================================================================== +# 2、受控基线(opt-in:AGENTLAB_QUERYCORE_PERF=1 才跑) +# ========================================================================== + +#: 打开基线的环境变量:默认不跑(一次基线是几百次真跑,不该混进日常回归) +PERF_ENV = "AGENTLAB_QUERYCORE_PERF" +#: 每一档跑多少次热执行(至少 100;显式调小只用于冒烟) +PERF_N_ENV = "AGENTLAB_QUERYCORE_PERF_N" +PERF_WARM = int(os.environ.get(PERF_N_ENV, "100")) +#: 冷启动样本各跑几次 +PERF_COLD = int(os.environ.get("AGENTLAB_QUERYCORE_PERF_COLD", "3")) +#: 样本写到哪儿:默认一个临时目录(也可以指定 AGENTLAB_QUERYCORE_PERF_OUT) +PERF_OUT_ENV = "AGENTLAB_QUERYCORE_PERF_OUT" +#: 两个并发档:客户端同时发几个 execute。名额上限取 max(1, L // 2):4 那一档有一半在排队,queue_ms 才有东西可验 +PERF_LEVELS = (1, 4) +#: 报告里逐个看的耗时 +REPORTED = ("total_ms", "run_ms", "database_ms", "queue_ms", "locate_ms", "closure_ms", "params_ms", "evidence_ms") + + +def percentile(values: list[int], pct: float) -> int | None: + """最近的排位(nearest-rank):样本少也不插值编一个中间值出来。""" + if not values: + return None + ordered = sorted(values) + rank = max(0, min(len(ordered) - 1, math.ceil(pct / 100 * len(ordered)) - 1)) + return ordered[rank] + + +async def cold_start(source_id: str) -> None: + """按「进程刚起来、还没连过这个源」的条件跑:清掉进程内的数据源连接池与现查缓存。 + + 真正的进程级冷启动要另起进程,这一版不做——报告里就按「清了进程内缓存」说清。""" + from app.data import coverage + from app.data.engine import engines + + await engines.invalidate(source_id) + for key in [k for k in coverage._LIVE if k and k[0] == source_id]: + coverage._LIVE.pop(key, None) + + +def sample_of(suite: str, level: int, phase: str, index: int, limit: int, wall_ms: int, outcome: Any, + failure: str | None) -> dict[str, Any]: + """一个原始样本:这次跑的哪一档、第几次、花了多久、交回什么、量到什么(量不到的照实 null)。""" + measured = outcome.as_dict().get("measurement") if outcome is not None else None + return {"suite": suite, "level": level, "phase": phase, "index": index, "slots_limit": limit, + "wall_ms": wall_ms, "ok": bool(outcome is not None and outcome.ok), + "status": None if outcome is None else outcome.status, + "run_id": None if outcome is None else outcome.run_id, + **({} if measured is None else {"phases": measured["phases"], "counts": measured["counts"], + "ids": measured["ids"]}), + "failure": failure} + + +async def run_sample(asset: dict, *, suite: str, level: int, phase: str, index: int, limit: int, + cold: bool = False) -> dict[str, Any]: + """跑一个样本。**失败也留下**:异常记成样本的 failure,不剔除。""" + if cold: + await cold_start(asset["source_id"]) + began = time.perf_counter() + outcome: Any = None + failure: str | None = None + try: + outcome = await execute_once(asset, trace=f"{suite}:{index}") + except Exception as e: # noqa: BLE001 - 失败样本也要留下来,不能悄悄丢掉 + failure = f"{type(e).__name__}: {e}" + return sample_of(suite, level, phase, index, limit, int((time.perf_counter() - began) * 1000), outcome, failure) + + +def group_key(sample: dict[str, Any]) -> tuple[str, int, str]: + return str(sample["suite"]), int(sample["level"]), str(sample["phase"]) + + +def summarize(samples: list[dict[str, Any]]) -> list[dict[str, Any]]: + """按档汇总:错误率算在**全部**样本上(失败不剔除),每个耗时的分位数只用真的量到它的那些样本。""" + groups: dict[tuple[str, int, str], list[dict[str, Any]]] = {} + for sample in samples: + groups.setdefault(group_key(sample), []).append(sample) + out: list[dict[str, Any]] = [] + for (suite, level, phase), group in sorted(groups.items()): + failed = [s for s in group if not s["ok"]] + row: dict[str, Any] = {"suite": suite, "level": level, "phase": phase, "n": len(group), + "slots_limit": group[0]["slots_limit"], "failed": len(failed), + "error_rate": round(len(failed) / len(group), 4), + "failure_kinds": sorted({str(s["failure"]) for s in failed if s["failure"]}) + or sorted({str(s.get("status")) for s in failed}), + "metrics": {}} + for name in REPORTED: + values = [int(s["phases"][name]) for s in group + if isinstance(s.get("phases"), dict) and isinstance(s["phases"].get(name), int)] + row["metrics"][name] = {"n": len(values), "p50": percentile(values, 50), "p95": percentile(values, 95), + "max": max(values) if values else None} + wall = [int(s["wall_ms"]) for s in group] + row["metrics"]["wall_ms"] = {"n": len(wall), "p50": percentile(wall, 50), "p95": percentile(wall, 95), + "max": max(wall)} + executed = [s["counts"]["executed_sql"] for s in group + if isinstance(s.get("counts"), dict) and isinstance(s["counts"].get("executed_sql"), int)] + row["counts"] = {"executed_sql_p50": percentile(executed, 50), "executed_sql_n": len(executed), + "llm_calls": sorted({s["counts"]["llm_calls"] for s in group + if isinstance(s.get("counts"), dict)}), + "planned_queries": sorted({s["counts"]["planned_queries"] for s in group + if isinstance(s.get("counts"), dict)})} + out.append(row) + return out + + +def render(summary: list[dict[str, Any]], header: str) -> str: + lines = [header, ""] + for row in summary: + lines.append(f"{row['suite']:>12} 并发{row['level']} 名额{row['slots_limit']} {row['phase']}: " + f"n={row['n']} 失败={row['failed']}({row['error_rate']:.1%})" + + (f" 失败类型={row['failure_kinds']}" if row["failure_kinds"] else "")) + for name in REPORTED: + stat = row["metrics"][name] + lines.append(f" {name:<14} n={stat['n']:<4} P50={stat['p50']}ms P95={stat['p95']}ms max={stat['max']}ms") + counts = row["counts"] + lines.append(f" 计数 executed_sql P50={counts['executed_sql_p50']}" + f" (n={counts['executed_sql_n']}) llm_calls={counts['llm_calls']}" + f" planned_queries={counts['planned_queries']}") + return "\n".join(lines) + + +async def run_baseline(asset: dict, out_dir: Path, monkeypatch) -> dict[str, Any]: + """跑完整一套:冷启动 + 并发 1 + 并发 4,原始样本落盘,返回汇总。""" + samples: list[dict[str, Any]] = [] + for index in range(PERF_COLD): + limit_slots(monkeypatch, 1) + samples.append(await run_sample(asset, suite="cold", level=1, phase="cold", index=index, limit=1, cold=True)) + for level in PERF_LEVELS: + limit = max(1, level // 2) + limit_slots(monkeypatch, limit) + index = 0 + while index < PERF_WARM: + batch = min(level, PERF_WARM - index) + results = await asyncio.gather(*[ + run_sample(asset, suite=f"concurrency-{level}", level=level, phase="warm", index=index + offset, + limit=limit) + for offset in range(batch)]) + samples.extend(results) + index += batch + (out_dir / "samples.jsonl").write_text( + "\n".join(json.dumps(s, ensure_ascii=False) for s in samples) + "\n", encoding="utf-8") + summary = summarize(samples) + code = {} + for name in ("app/ledger/querycore.py", "app/engine/runner.py"): + code[name] = hashlib.sha256((Path(__file__).resolve().parents[1] / name).read_bytes()).hexdigest()[:12] + header = (f"== QueryCore K13 基线(合成数据) ==\n" + f"样本目录:{out_dir}(samples.jsonl / summary.json)\n" + f"代码快照:{code}\n" + f"机器:{platform.platform()} / python {platform.python_version()} / {os.cpu_count()} 核\n" + f"数据:{S.CURRENT['source']}(临时 SQLite,合成店铺库);参数:{INPUTS};指标:{METRIC_IDS}\n" + f"预算:timeout_s={querycore.DEFAULT_TIMEOUT_S} 秒、max_queries={querycore.DEFAULT_MAX_QUERIES}\n" + f"冷启动 = 每次先清掉进程内数据源连接池与现查缓存的那一次(不重启进程):代表「连接/现查缓存还没热」;\n" + f" 进程级的一次性开销(模块按需导入、编译)只落在整套基线的**第一次**执行上,是冷启动那一档的 max\n" + f"热执行 = 连着跑(前面那些一次性开销已经付过)\n" + f"每档热执行 {PERF_WARM} 次(要求 ≥100)、冷启动 {PERF_COLD} 次;失败样本不剔除\n" + f"**没有生产负载:这一份推不出生产的 P50/P95**") + report = render(summary, header) + (out_dir / "summary.json").write_text(json.dumps({"header": header, "code_hashes": code, "params": INPUTS, + "metric_ids": METRIC_IDS, "levels": list(PERF_LEVELS), + "warm": PERF_WARM, "cold": PERF_COLD, + "summary": summary}, ensure_ascii=False, indent=2), + encoding="utf-8") + print("\n" + report) + return {"samples": samples, "summary": summary, "report": report, "dir": str(out_dir)} + + +@pytest.mark.skipif(not os.environ.get(PERF_ENV), reason=f"受控基线要 {PERF_ENV}=1 才跑(默认不跑几百次真跑)") +async def test_the_controlled_baseline(asset, monkeypatch): + """受控基线:冷启动/热执行分开、并发 1 与 4 两档、原始样本 + P50/P95 + 错误率。失败样本不剔除。""" + out_dir = Path(os.environ.get(PERF_OUT_ENV) or tempfile.mkdtemp(prefix="agentlab-querycore-perf-")) + out_dir.mkdir(parents=True, exist_ok=True) + baseline = await run_baseline(asset, out_dir, monkeypatch) + + got = {(row["suite"], row["phase"]) for row in baseline["summary"]} + assert got == {("cold", "cold"), ("concurrency-1", "warm"), ("concurrency-4", "warm")}, got + hot = [row for row in baseline["summary"] if row["phase"] == "warm"] + assert hot, "至少要有热执行那一档" + for row in hot: + assert row["n"] == PERF_WARM, f"{row['suite']} 跑了 {row['n']} 次,应当跑满 {PERF_WARM} 次" + # 默认就是「至少 100 次」;显式把次数调小(冒烟)就按调小的算,报告里写着实际次数 + assert row["n"] >= 100 or PERF_N_ENV in os.environ, f"基线要求每档至少 100 次,实际 {row['n']}" + assert row["metrics"]["total_ms"]["p50"] is not None + assert row["metrics"]["total_ms"]["p95"] is not None + # 每次都要把这次真的执行了几条 SQL 记下来(跑得成的那些) + assert row["counts"]["executed_sql_n"] > 0 + # 并发 4 那一档要能看到排队:一半样本在等名额 + queued = [s for s in baseline["samples"] + if s["suite"] == "concurrency-4" and isinstance(s.get("phases"), dict) + and isinstance(s["phases"].get("queue_ms"), int) and s["phases"]["queue_ms"] > 0] + assert queued, "并发 4(名额 2)那一档必须有样本真的排了队,queue_ms 才谈得上被验证" + assert all(s["counts"]["llm_calls"] == 0 for s in baseline["samples"] + if isinstance(s.get("counts"), dict) and s["counts"].get("llm_calls") is not None) + assert (out_dir / "samples.jsonl").exists() and (out_dir / "summary.json").exists() diff --git a/backend/tests/test_querycore_user_access.py b/backend/tests/test_querycore_user_access.py new file mode 100644 index 00000000..632a16b4 --- /dev/null +++ b/backend/tests/test_querycore_user_access.py @@ -0,0 +1,1125 @@ +"""K14:普通使用者按口径取数的统一授权、服务端补上的工具绑定、只列有授权的口径清单、服务端准备的那条执行路。 + +这份文件盯住这几条: + +1. **授权在 QueryCore 一处兜底。** compose 这一档(问数、固定请求路由、自动路由、父 Run 的工具调用)在**固定 workflow + + version 之后、起 Run 之前**核资产授权(apps/access.caliber_role:同一张 AppGrant + 应用当前发布版精确固定着这一版): + use 及以上才放行,没有授权当场 403 `querycore_not_authorized`,**一条运行都不起**;builder / admin / 关登录由调用方 + 显式放行;actor 缺失(认不出是谁)按普通使用者算,照拒。 +2. **行级范围照授权的那一档。** use 只看自己提交的记录,observe 看全部(records/access.scope_of_run:口径里的记录表数据源)。 +3. **工具是服务端绑上的、模型看得见。** 有授权口径可用时 chat/launch 把 `caliber_query` 补进 Agent 的 tools(用户不用在 + 画布上画);auth/chat_policy 的白名单允许这个只读工具(模型清单里列得出来),能不能执行仍由 QueryCore 按授权判。 +4. **口径清单只列有授权的版本。** look/calibers 对普通使用者只列 `usable_calibers` 里那些版本(builder 不变)。 +5. **服务端准备的执行有显式绑定、白名单、遮罩、只读与父 Run 证据。** `execute_prepared` 搭最小的父图、经 `user_chat_run` + 起一次探索父 Run,实际从 `caliber_query` 工具走(派生的子运行就是那次固定执行),交回与 `execute` 同形的 Outcome。 + +数据全是合成的(临时 SQLite 库、合成标量指标),不连真实业务库;这些指标不是任何真实业务口径。 +""" +from __future__ import annotations + +import asyncio +import json +import uuid +from typing import Any + +import pytest +from httpx import ASGITransport, AsyncClient +from sqlalchemy import select + +from app.api import deps +from app.api.deps import Principal +from app.apps.access import usable_calibers +from app.auth import chat_policy +from app.chat.launch import bind_caliber_tool, user_chat_run +from app.db.base import SessionLocal +from app.db.models import Run +from app.engine.runner import run_manager +from app.ledger import nlchange, querycore +from app.look.calibers import CaliberKind, permitted_versions +from app.main import app +from app.tools.datasource import MASK_RESULTS_OPTION, READ_ONLY_OPTION +from tests import ledger_samples as S +from tests.fakes import auth_env +from tests.publication_samples import add_record, add_version, confirm, make_workflow, publish +from tests.test_caliber_query_tool import grant_caliber, records_caliber_graph, records_source + +#: 口径卡的节点 id(源头口径卡) +CARD = "card" +#: 取数窗口:start(含)/ end(不含) +WINDOW = "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'" +#: 这次入口取值:2026-09-01 ≤ paid_at < 2026-09-08,只算 paid:100 + 50.5 + 20 +INPUTS = {"start": "2026-09-01", "end": "2026-09-08"} +WINDOW_SUM = 170.5 + + +def upload_graph(*, include_open: bool = False) -> dict[str, Any]: + """入口 → 一条取数(上传表格)→ 口径卡 → 报告 → 出口。这张表是 ledger_samples 的虚构店铺库。 + + include_open 再加一档状态(v2 的口径):换个算法就换了取数(等价于「图上改了东西」),让两版各有自己的清单与结果。""" + status = "status IN ('paid', 'open')" if include_open else "status = 'paid'" + return S.chain( + S.node("start", "input", fields=[{"name": "start", "type": "string", "required": True}, + {"name": "end", "type": "string", "required": True}]), + S.node("sales", "tool", tool=S.tool(), + args={"sql": f"SELECT SUM(amount) AS gmv, count(*) AS orders FROM orders " + f"WHERE {status} {WINDOW}"}), + S.node(CARD, "metrics", caliber="合成周销售", caliber_version="v1", metrics=[ + {"id": "gmv", "name": "销售额", "unit": "元", "decimals": 2, "expression": "cell(nodes.sales, 0, 'gmv')"}, + {"id": "orders", "name": "单数", "unit": "单", "expression": "cell(nodes.sales, 0, 'orders')"}, + ]), + S.node("write", "report", instructions="写周销售"), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.write.text }}"}]), + ) + + +def agent_graph(tools: tuple[str, ...] = ()) -> dict[str, Any]: + """一张普通使用者搭得出来的问数图:入口 → Agent(绑数据源查询)→ 出口。""" + return S.chain( + S.node("start", "input", fields=[{"name": "question"}]), + S.node("ask", "agent", prompt="{{ input.question }}", tools=list(tools) or [S.tool()], max_steps=4), + S.node("out", "output", fields=[{"name": "回答", "value": "{{ nodes.ask.text }}"}]), + ) + + +def values_of(outcome: querycore.Outcome) -> dict[str, Any]: + return {m["id"]: m["value"] for m in outcome.as_dict()["metrics"]} + + +async def execute(asset: dict, *, metric_ids: list[str] | None = None, inputs: dict[str, Any] | None = None, + **kw: Any) -> querycore.Outcome: + """走服务入口跑一次(agent 之外的那条路):不给 actor 时按当前请求的身份算(HTTP 入口就是这样)。""" + async with SessionLocal() as session: + return await querycore.execute(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=metric_ids or ["gmv"], + inputs=INPUTS if inputs is None else inputs, **kw) + + +def as_user(name: str = "uma", role: str = "user") -> Any: + """这次请求的人是这个人(HTTP 中间件写的就是它);返回 token,用完 reset。""" + return deps.set_principal(Principal(username=name, role=role, verified=True, mode="local")) + + +async def runs_matching(*, workflow_id: str | None = None, started_by: str | None = None) -> int: + """库里符合这几个条件的运行条数:用例按**自己**的口径或身份数,别的用例、别的 worker 留下的行串不进来。""" + stmt = select(Run.id) + if workflow_id is not None: + stmt = stmt.where(Run.workflow_id == workflow_id) + if started_by is not None: + stmt = stmt.where(Run.started_by == started_by) + async with SessionLocal() as session: + return len(list((await session.execute(stmt)).scalars())) + + +async def add_record_row(source_id: str, actor: str) -> None: + """往这张记录表里追加一行(谁提交的):行级范围是 mine 时别人看不见它。""" + from app.records import store + from app.records.tables import columns_of, path_of, table_of_source + + async with SessionLocal() as session: + table = await table_of_source(session, source_id) + store.append(path_of(table), columns_of(table), {"门店": "二店", "数量": 2}, version=table.version, + run_id=None, actor=actor, action_key=uuid.uuid4().hex) + + +async def app_of_source(source_id: str) -> str: + from app.records.tables import table_of_source + + async with SessionLocal() as session: + table = await table_of_source(session, source_id) + return str(table.app_id) + + +@pytest.fixture(autouse=True) +async def engine_up(tmp_path): + await run_manager.setup() + await S.fresh_source(tmp_path / "user_access_orders.db") + yield + await run_manager.shutdown() + + +@pytest.fixture +async def client(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c: + yield c + + +# ========================================================================== +# 1、授权:use 能用、observe 看全部、没有授权当场拒 +# ========================================================================== + + +async def test_use_sees_only_their_own_rows_and_observe_sees_all(client): + """有授权(use)才跑得成,且只看得到自己提交的记录;换成 observe 就看全部——两处都是同一份授权判出来的。""" + from app.db.models_apps import AppGrant + + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("uma", "user") + source_id, name = await records_source(grants={"uma": "use"}) + await add_record_row(source_id, "别人") # 别人的一行:use 看不见,observe 看得见 + asset = await make_workflow(graph=records_caliber_graph(name)) + await publish(admin, asset) + await grant_caliber(asset["workflow_id"], 1, "uma", "use") + + token = as_user("uma") + try: + use = await execute(asset, metric_ids=["n"], inputs={}, actor="uma") + finally: + deps.reset_principal(token) + assert use.ok, use.problems + assert values_of(use) == {"n": 1}, "use 档只看自己提交的那一行" + + async with SessionLocal() as session: + session.add(AppGrant(app_id=await app_of_source(source_id), principal_kind="user", principal="uma", + role="observe")) + await session.commit() + token = as_user("uma") + try: + observe = await execute(asset, metric_ids=["n"], inputs={}, actor="uma") + finally: + deps.reset_principal(token) + assert observe.ok, observe.problems + assert values_of(observe) == {"n": 2}, "observe 档看全部" + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_an_unauthorized_caliber_is_refused_before_any_run(client): + """没有授权:上传表格那一档口径也当场拒(403 querycore_not_authorized),**一条运行都不起**。""" + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("uma", "user") + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) + before = await runs_matching(workflow_id=asset["workflow_id"]) + token = as_user("uma") + try: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await execute(asset, actor=None) + finally: + deps.reset_principal(token) + assert caught.value.code == querycore.NOT_AUTHORIZED and caught.value.status_code == 403 + assert caught.value.problems[0]["version"] == 1 and caught.value.problems[0]["workflow_id"] == asset["workflow_id"] + assert await runs_matching(workflow_id=asset["workflow_id"]) == before, "起 Run 之前就拒:这次没留下运行" + + # 给它一份授权(应用当前发布版固定着这一版 + 至少 use)之后同样这条路就通了 + await grant_caliber(asset["workflow_id"], 1, "uma", "use") + token = as_user("uma") + try: + allowed = await execute(asset) + finally: + deps.reset_principal(token) + assert allowed.ok and values_of(allowed) == {"gmv": WINDOW_SUM} + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_a_fixed_request_cannot_bypass_the_asset_grant(client): + """固定请求路由(K12)交回的那条固定请求照样过同一道授权:换一个入口绕不过去,也不回退旧 Agent 路径。""" + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("uma", "user") + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) + request = {"workflow_id": asset["workflow_id"], "card_id": CARD, "metric_ids": ["gmv"], "inputs": INPUTS} + async with SessionLocal() as session: + routed = await nlchange.route(session, request=request) + assert routed.mode == nlchange.ROUTE_EXECUTE and routed.request["version"] == 1 + call = {key: value for key, value in routed.request.items() if key != "purpose"} + + before = await runs_matching(workflow_id=asset["workflow_id"]) + token = as_user("uma") + try: + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.execute(session, purpose=str(routed.request["purpose"]), **call) + assert caught.value.code == querycore.NOT_AUTHORIZED + assert await runs_matching(workflow_id=asset["workflow_id"]) == before, "这条路上也没有起任何运行" + await grant_caliber(asset["workflow_id"], 1, "uma", "use") + outcome = await querycore.execute(session, purpose=str(routed.request["purpose"]), **call) + finally: + deps.reset_principal(token) + assert outcome.ok and values_of(outcome) == {"gmv": WINDOW_SUM} + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_a_missing_actor_is_refused_when_login_is_on(client): + """开了登录却认不出这次是谁:按普通使用者算——资产授权查不到主体就是没有授权,照拒(不拿「认不出」当放行)。""" + admin = await auth_env.turn_on_local() + try: + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) + token = deps.set_principal(None) + try: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await execute(asset) + finally: + deps.reset_principal(token) + assert caught.value.code == querycore.NOT_AUTHORIZED + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_builder_and_admin_are_explicitly_allowed(client): + """builder / admin 由调用方显式放行:它们不按资产授权收窄(那几档不写进资产授权函数),没有授权也跑得成。""" + admin = await auth_env.turn_on_local() + try: + builder = f"b{uuid.uuid4().hex[:8]}" # 这两个身份自己的一份:别的用例留下的授权串不进来 + await auth_env.make_user(builder, "builder") + top_name = f"a{uuid.uuid4().hex[:8]}" + await auth_env.make_user(top_name, "admin") + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) + async with SessionLocal() as session: + # 按**这一版**看:别的工作流上「给所有人」的授权留在库里(测试会话共用一个库),不影响这一版没有授权 + assert (asset["workflow_id"], 1) not in await usable_calibers(session, builder) + built = await execute(asset, actor=builder) + assert built.ok and values_of(built) == {"gmv": WINDOW_SUM} + token = as_user(top_name, role="admin") + try: + top = await execute(asset) + finally: + deps.reset_principal(token) + assert top.ok and values_of(top) == {"gmv": WINDOW_SUM} + finally: + await admin.aclose() + await auth_env.reset() + + +# ========================================================================== +# 2、工具是服务端绑的、白名单允许它 +# ========================================================================== + + +async def test_the_agent_gets_the_caliber_tool_only_when_there_is_one_to_use(client): + """有授权口径可用时把 caliber_query 补进 Agent 的 tools(改的是副本,用户的图不动);一份也没有、或者不是普通使用者就不补。 + + 「一份也没有」用**停用**的身份来立:测试会话共用一个库,别的用例给「所有人」的授权(AppGrant.principal_kind=everyone) + 会留在库里、命中任何名字——停用的身份在资产授权那一层就是没有主体(apps/access._subject),不受那些授权影响。""" + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" # 这个身份自己的一份 + await auth_env.make_user(who, "user") + gone = f"u{uuid.uuid4().hex[:8]}" + await auth_env.make_user(gone, "user", disabled=True) + await auth_env.make_user("bob", "builder") + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) + graph = agent_graph() + async with SessionLocal() as session: + # 一份也没有(停用的人):原样交回(不给模型一个一调就被拒的工具) + assert await bind_caliber_tool(session, graph, gone) == graph + # builder:它本来就能自己在画布上绑,不替它补 + assert await bind_caliber_tool(session, graph, "bob") == graph + await grant_caliber(asset["workflow_id"], 1, who, "use") + bound = await bind_caliber_tool(session, graph, who) + tools = bound["nodes"][1]["data"]["config"]["tools"] + assert tools == [S.tool(), querycore.CALIBER_QUERY], tools + assert graph["nodes"][1]["data"]["config"]["tools"] == [S.tool()], "补的是副本,调用方的图一个字不动" + assert chat_policy.chat_graph_problem(bound) is None, "白名单允许这个只读工具(模型清单里列得出来)" + assert querycore.CALIBER_QUERY in chat_policy.CHAT_BUILTIN_TOOLS + from app.api.copilot import _tool_catalog + + listing = _tool_catalog([], builtins=chat_policy.CHAT_BUILTIN_TOOLS) + assert querycore.CALIBER_QUERY in listing, "使用者的提示词里列得出口径查询:模型看得到它" + + async with SessionLocal() as session: + memory_scope, options, running = await user_chat_run(session, graph, who) + assert memory_scope == f"chat:{who}" and options == {MASK_RESULTS_OPTION: True, READ_ONLY_OPTION: True} + assert querycore.CALIBER_QUERY in running["nodes"][1]["data"]["config"]["tools"] + finally: + await admin.aclose() + await auth_env.reset() + + +# ========================================================================== +# 3、口径清单只列有授权的版本 +# ========================================================================== + + +async def test_look_lists_only_authorized_versions_for_a_plain_user(client): + """look/calibers:普通使用者只列有授权的那一版(别的连解析都不做);builder 照旧列全部。""" + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" # 这个身份自己的一份:别的工作留下的授权串不进来 + await auth_env.make_user(who, "user") + mine = await make_workflow(graph=upload_graph()) + await publish(admin, mine) + other = await make_workflow(graph=upload_graph()) + await publish(admin, other) + await grant_caliber(mine["workflow_id"], 1, who, "use") + + person = Principal(username=who, role="user", verified=True, mode="local") + async with SessionLocal() as session: + permitted = await permitted_versions(session, person) + assert (mine["workflow_id"], 1) in permitted, "有授权的那一版在清单里" + seen = await CaliberKind.load(session, actor=person) + assert seen.items, "有授权的那一版要列出来" + assert mine["workflow_id"] in {item.workflow_id for item in seen.items} + assert all((item.workflow_id, item.version) in permitted for item in seen.items) + assert other["workflow_id"] not in {item.workflow_id for item in seen.items} + # 搭建者不受这一层收窄(行为不变) + builder = Principal(username="bob", role="builder", mode="local") + assert await permitted_versions(session, builder) is None + everything = await CaliberKind.load(session, actor=builder) + assert {mine["workflow_id"], other["workflow_id"]} <= {item.workflow_id for item in everything.items} + finally: + await admin.aclose() + await auth_env.reset() + + +# ========================================================================== +# 4、服务端准备的那条路:显式绑定、白名单、遮罩/只读、父 Run 证据 +# ========================================================================== + + +async def test_the_prepared_path_runs_through_the_tool_and_keeps_the_parent_evidence(client): + """execute_prepared:最小父图(入口 → caliber_query → 出口)、经 user_chat_run 起探索父 Run、真的从工具走一次。 + + 交回的 Outcome 与 execute 同形:run_id 是父 Run(显式绑定、遮罩/只读、每条 query artifact 的证据都在它上面), + execution_run_id 是它派生出来真正跑那几条 SQL 的子运行。""" + from app.engine.evidence_reader import read_sealed + + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("uma", "user") + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) + await grant_caliber(asset["workflow_id"], 1, "uma", "use") + + async with SessionLocal() as session: + outcome = await querycore.execute_prepared( + session, workflow_id=asset["workflow_id"], card_id=CARD, metric_ids=["gmv", "orders"], + inputs=INPUTS, actor="uma", origin={"conversation_id": "c1", "turn_id": "t1"}) + assert outcome.ok, outcome.problems + assert values_of(outcome) == {"gmv": WINDOW_SUM, "orders": 3} + assert outcome.version == 1 and outcome.purpose == querycore.DEFAULT_PURPOSE + assert outcome.execution_run_id and outcome.execution_run_id != outcome.run_id + + async with SessionLocal() as session: + parent = await session.get(Run, outcome.run_id) + child = await session.get(Run, outcome.execution_run_id) + assert parent.run_class == "exploratory" and parent.origin_kind == "chat" + assert parent.started_by == "uma" and parent.origin["conversation_id"] == "c1" + # 遮罩 + 只读:和普通问数一样的两条边界;预算也记在父 Run 上(子运行照它走) + assert parent.options[MASK_RESULTS_OPTION] is True and parent.options[READ_ONLY_OPTION] is True + assert parent.options[querycore.BUDGET_OPTION]["max_queries"] + assert parent.memory_scope == "chat:uma" + # 显式绑定:父图上那个节点就是口径查询,参数写死在图上(不是模型挑的) + [bound] = [n for n in parent.graph["nodes"] if n["data"]["config"].get("tool") == querycore.CALIBER_QUERY] + assert bound["data"]["config"]["args"] == {"workflow": asset["workflow_id"], "card": CARD, + "metric_ids": ["gmv", "orders"], "inputs": INPUTS} + # 派生的子运行:明确的父子关系,跑的是那一次固定执行 + assert child is not None and child.origin["parent_run_id"] == parent.id + assert child.origin["service"] == "querycore" and child.options[READ_ONLY_OPTION] is True + # 证据:父 Run 的台账里逐条记着这次口径查询的查询快照(工件、来源、执行身份) + sealed = await read_sealed(parent.id) + payload = sealed.payload_of([querycore.PREPARED_NODE]) + assert payload and payload["kind"] == querycore.CALIBER_QUERY and payload["run_id"] == child.id + assert [q["execution_id"] for q in payload["queries"]] == [q["execution_id"] for q in outcome.queries] + assert {q["artifact"] for q in outcome.queries} <= set(sealed.queries) + # 普通使用者读得到这次运行(它自己发起、origin_kind=chat、在工具边界遮过) + assert await deps.run_events_readable(Principal(username="uma", role="user", verified=True, mode="local"), + parent) + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_a_moved_recommended_version_is_reported_not_substituted(client): + """点名的那一版固定并授权过,工具那条路固定的是**推荐版**:推荐版中途换过时照实记下来、不把另一版的数当这一版交出。 + + (这里让这个人两版都有授权,好让执行真的走到「跑的是另一版」那一步;只有一版授权时另一次执行会先在授权那道门被拒。)""" + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" + await auth_env.make_user(who, "user") + first = await make_workflow(graph=upload_graph()) + await publish(admin, first) # v1 + second = await add_version(first, upload_graph(include_open=True), version=2) + await publish(admin, second, version=2) # v2 成了推荐版 + await grant_caliber(first["workflow_id"], 1, who, "use") + await grant_caliber(first["workflow_id"], 2, who, "use") + + async with SessionLocal() as session: + outcome = await querycore.execute_prepared(session, workflow_id=first["workflow_id"], card_id=CARD, + metric_ids=["gmv"], inputs=INPUTS, version=1, actor=who) + assert outcome.ok is False and outcome.version == 2 + assert querycore.VERSION_MOVED in [p["code"] for p in outcome.problems] + assert values_of(outcome)["gmv"] != WINDOW_SUM, "跑的是另一版:值也不是点名那一版的" + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_the_prepared_path_refuses_before_launching_and_masks_the_result(client, tmp_path): + """没有授权:这条路也在起任何运行之前拒;有授权但列被遮罩:照实交回遮罩过的结果(值不交出去)。""" + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" # 这个身份自己的一份:别的用例留下的运行串不进来 + await auth_env.make_user(who, "user") + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) + before = await runs_matching(started_by=who) + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.execute_prepared(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=["gmv"], inputs=INPUTS, actor=who) + assert caught.value.code == querycore.NOT_AUTHORIZED and caught.value.status_code == 403 + assert await runs_matching(started_by=who) == before, "没授权就连父 Run 都不起" + + await grant_caliber(asset["workflow_id"], 1, who, "use") + await S.set_source(tmp_path / "user_access_orders.db", options={"mask_columns": ["gmv"]}) + async with SessionLocal() as session: + masked = await querycore.execute_prepared(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=["gmv"], inputs=INPUTS, actor=who) + [metric] = masked.metrics + assert metric.get("masked") is True and metric["value"] is None + assert masked.ok is False and querycore.METRIC_MASKED in [p["code"] for p in masked.problems] + # 父 Run 上留给证据的那一份也只有遮罩后的说法,原值一个字都不在 + from app.engine.evidence_reader import read_sealed + + payload = (await read_sealed(masked.run_id)).payload_of([querycore.PREPARED_NODE]) + assert payload["metrics"][0]["masked"] is True and payload["metrics"][0]["value"] is None + finally: + await admin.aclose() + await auth_env.reset() + + +# ========================================================================== +# 5、正式那一档也要授权(安全复核 1) +# ========================================================================== + + +async def test_the_formal_path_also_needs_the_asset_grant(client): + """正式运行**也**要这一版口径的资产授权:没有授权当场 403,起了任何运行都算漏;授权之后还要发布依据齐。""" + from app.apps import publications + + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" + await auth_env.make_user(who, "user") + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) # 有清单、还没有验证记录与审阅 + before = await runs_matching(workflow_id=asset["workflow_id"]) + + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as caught: + await querycore.execute_formal(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=["gmv"], inputs=INPUTS, actor=who) + assert caught.value.code == querycore.NOT_AUTHORIZED and caught.value.status_code == 403 + assert caught.value.problems[0]["purpose"] == publications.PURPOSE_FORMAL + assert await runs_matching(workflow_id=asset["workflow_id"]) == before, "正式这一档也在起 Run 之前拒" + + # 授权之后是**另一道**(发布依据):机器码是 judge 的原码,不是 not_authorized + await grant_caliber(asset["workflow_id"], 1, who, "use") + async with SessionLocal() as session: + with pytest.raises(querycore.QueryCoreRefused) as proof: + await querycore.execute_formal(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=["gmv"], inputs=INPUTS, actor=who) + assert proof.value.code == publications.RECORD_MISSING and proof.value.code != querycore.NOT_AUTHORIZED + assert await runs_matching(workflow_id=asset["workflow_id"]) == before + + # 两道都过:发布依据补齐(独立核算 + 人工确认)之后正式跑得成 + record = await add_record(asset, metric_ids=("gmv",)) + await confirm(asset, record) + await publish(admin, asset) + async with SessionLocal() as session: + outcome = await querycore.execute_formal(session, workflow_id=asset["workflow_id"], card_id=CARD, + metric_ids=["gmv"], inputs=INPUTS, actor=who) + assert outcome.ok and values_of(outcome) == {"gmv": WINDOW_SUM} + assert outcome.publication["identity"] == publications.PROVEN + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_a_formal_parent_run_by_a_plain_user_is_refused_without_a_grant(client): + """应用图里引用一份没授权给它的口径:正式父 Run 里那一次调用照样被拒(工具那一层也过同一道授权)。""" + from app.apps import publications + from tests.test_caliber_query_tool import gated_parent_graph + + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" + await auth_env.make_user(who, "user") + asset = await make_workflow(graph=upload_graph()) + graph = gated_parent_graph(asset["workflow_id"], metric_ids=["gmv"]) + run = await run_manager.start(graph=graph, input_payload={}, run_class="formal", started_by=who) + await _wait_for(run.id, ("interrupted",)) + await confirm(asset, await add_record(asset, metric_ids=("gmv",))) # 依据齐(不给资产授权) + await publish(admin, asset) + await run_manager.resume(run.id, {"approved": True}) + done = await _settled(run.id) + assert done.status == "failed" and querycore.NOT_AUTHORIZED in str(done.error or ""), done.error + assert "正式" in str(done.error or ""), "说法里说清这是正式那一档" + finally: + await admin.aclose() + await auth_env.reset() + + +# ========================================================================== +# 6、普通使用者读运行:图上、事件里不留口径的内部身份(安全复核 2) +# ========================================================================== + +#: 事件里**不许**出现的键:口径身份、发布清单、selection、哈希、工件 id、参数材料 +INTERNAL_EVENT_KEYS = ("args", "preview", "artifact", "query_artifact", "query_artifacts", "schema_artifact", + "evidence", "parameters", "origin", "workflow_id", "card_id", "version", "manifest", + "selection", "identity", "execution_hash", "graph_hash", "selection_hash", "closure_hash", + "vars") + + +def _cookie(client: Any) -> str: + return f"agentlab_session={client.cookies.get('agentlab_session')}" + + +async def _ws(path: str, cookie: str | None) -> list[dict]: + """把一次 WebSocket 握手原样交给整个应用(中间件 + 路由级依赖 + 路由),记下发出去的帧。""" + inbox: Any = asyncio.Queue() + await inbox.put({"type": "websocket.connect"}) + sent: list[dict] = [] + + async def receive(): + return await inbox.get() + + async def send(message): + sent.append(message) + if message["type"] == "websocket.close": + await inbox.put({"type": "websocket.disconnect", "code": 1000}) + + headers = [(b"host", b"test")] + ([(b"cookie", cookie.encode())] if cookie else []) + scope = {"type": "websocket", "asgi": {"version": "3.0"}, "scheme": "ws", "http_version": "1.1", "path": path, + "raw_path": path.encode(), "query_string": b"", "root_path": "", "headers": headers, + "client": ("127.0.0.1", 50000), "server": ("test", 80), "subprotocols": [], "state": {}} + await asyncio.wait_for(app(scope, receive, send), 10) + return sent + + +async def _wait_for(run_id: str, statuses: tuple[str, ...]) -> Any: + deadline = asyncio.get_running_loop().time() + 30.0 + while asyncio.get_running_loop().time() < deadline: + async with SessionLocal() as session: + row = await session.get(Run, run_id) + if row is not None and row.status in statuses: + return row + await asyncio.sleep(0.05) + raise AssertionError(f"运行 {run_id} 没有进入 {statuses}") + + +async def _settled(run_id: str) -> Any: + return await _wait_for(run_id, ("succeeded", "failed", "cancelled", "interrupted")) + + +async def _allow_chat(admin: Any) -> None: + r = await admin.put("/api/auth/settings", json={"user_can_chat": True}) + assert r.status_code == 200, r.text + + +async def prepared_parent(client, *, who: str) -> tuple[dict, Any]: + """一份合成口径 + 一次普通使用者的 prepared 执行:交回 (资产, Outcome)。调用方自己开登录、给授权。 + + client 是**发布用的**客户端(开登录之后发请求要带 CSRF 头,admin 那个就是)。""" + asset = await make_workflow(graph=upload_graph()) + await publish(client, asset) + await grant_caliber(asset["workflow_id"], 1, who, "use") + async with SessionLocal() as session: + outcome = await querycore.execute_prepared( + session, workflow_id=asset["workflow_id"], card_id=CARD, metric_ids=["gmv", "orders"], inputs=INPUTS, + actor=who, origin={"conversation_id": "c1", "turn_id": "t1"}) + assert outcome.ok, outcome.problems + return asset, outcome + + +async def test_a_plain_user_reads_the_run_without_the_internal_caliber(client): + """普通使用者读得到自己这次运行,但运行图与事件里读不到口径的内部身份;指标值、状态、进度、别的节点都在。""" + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" + await auth_env.make_user(who, "user") + await _allow_chat(admin) + asset, outcome = await prepared_parent(admin, who=who) + person = await auth_env.login(who) + + graph_body = (await person.get(f"/api/runs/{outcome.run_id}/graph")).json() + [node] = [n for n in graph_body["graph"]["nodes"] if n["id"] == querycore.PREPARED_NODE] + args = node["data"]["config"]["args"] + assert set(args) == {"caliber"}, args + assert asset["workflow_id"] not in json.dumps(graph_body, ensure_ascii=False) + assert graph_body["workflow_id"] is None and graph_body["version"] is None + + events = (await person.get(f"/api/runs/{outcome.run_id}/events")).json() + dumped = json.dumps(events, ensure_ascii=False) + assert asset["workflow_id"] not in dumped and f'"{CARD}"' not in dumped, "事件里不许出现口径身份" + mine = [e for e in events if e["node_id"] == querycore.PREPARED_NODE] + assert mine, "口径查询节点的事件要在(进度看得见)" + for event in mine: + assert not [k for k in event["data"] if k in INTERNAL_EVENT_KEYS], event + ends = [e for e in mine if e["type"] == "tool.end"] + assert ends and ends[0]["data"]["tool"] == querycore.CALIBER_QUERY + assert ends[0]["data"]["duration_ms"] is not None, "花了多久留着" + assert [m["id"] for m in ends[0]["data"]["result"]["metrics"]] == ["gmv", "orders"], "指标值留着" + assert {m["value"] for m in ends[0]["data"]["result"]["metrics"]} == {WINDOW_SUM, 3} + assert ends[0]["data"]["result"]["ok"] is True and ends[0]["data"]["result"]["status"] == "succeeded" + # 别的节点的事件原样:不因为这一条口径查询就把普通聊天的事件清空 + others = [e for e in events if e["node_id"] and e["node_id"] != querycore.PREPARED_NODE] + assert others, "别的节点的事件还在" + assert any("artifact" in e["data"] or "preview" in e["data"] for e in others), "别的节点照原样给(没被清空)" + + # 搭建者读到的还是原件:图上参数、事件里的工件都在 + raw = (await admin.get(f"/api/runs/{outcome.run_id}/graph")).json() + [raw_node] = [n for n in raw["graph"]["nodes"] if n["id"] == querycore.PREPARED_NODE] + assert raw_node["data"]["config"]["args"]["workflow"] == asset["workflow_id"] + raw_events = (await admin.get(f"/api/runs/{outcome.run_id}/events")).json() + assert asset["workflow_id"] in json.dumps(raw_events, ensure_ascii=False) + await person.aclose() + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_the_websocket_stream_goes_through_the_same_projection(client): + """实时流和事件接口是同一条路:WS 补的历史、推的实时事件都过同一份投影。""" + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" + await auth_env.make_user(who, "user") + await _allow_chat(admin) + asset, outcome = await prepared_parent(admin, who=who) + person = await auth_env.login(who) + frames = await _ws(f"/api/runs/{outcome.run_id}/stream", _cookie(person)) + assert frames[0]["type"] == "websocket.accept" + texts = [f.get("text") or "" for f in frames if f["type"] == "websocket.send"] + assert any("stream.end" in text for text in texts), texts[-3:] + dumped = "\n".join(texts) + assert asset["workflow_id"] not in dumped and f'"{CARD}"' not in dumped, "实时流里也不许出现口径身份" + assert querycore.CALIBER_QUERY in dumped, "口径查询那一步在(进度看得见)" + results = [json.loads(text)["data"]["result"] for text in texts + if '"result"' in text and isinstance(json.loads(text).get("data", {}).get("result"), dict)] + assert results and results[0]["ok"] is True, "结果摘要里留着算成没算成" + assert [m["id"] for m in results[0]["metrics"]] == ["gmv", "orders"], "指标值留着" + + # 实时那一段(_pump)收的是总线上推来的事件:过的是同一个投影 + from app.api import runs as runs_api + from app.core.events import RunEventModel + + live: list[dict] = [] + + class _Socket: + async def send_json(self, payload: dict[str, Any]) -> None: + live.append(payload) + + async def close(self) -> None: + return None + + async def _live(): + yield RunEventModel(run_id=outcome.run_id, type="tool.end", node_id=querycore.PREPARED_NODE, + data={"tool": querycore.CALIBER_QUERY, "provided": "args", + "args": {"workflow": asset["workflow_id"]}, "preview": "{}"}) + + graph = querycore.prepared_graph(asset["workflow_id"], card_id=CARD, metric_ids=["gmv"], inputs=INPUTS) + token = deps.set_principal(Principal(username=who, role="user", verified=True, mode="local")) + try: + await runs_api._pump(_Socket(), _live(), outcome.run_id, runs_api.run_projection(graph)) + finally: + deps.reset_principal(token) + assert live[0]["data"]["tool"] == querycore.CALIBER_QUERY and "args" not in live[0]["data"] + await person.aclose() + finally: + await admin.aclose() + await auth_env.reset() + + +def test_the_projection_only_applies_to_ordinary_readers(): + """谁拿投影:开登录后的使用者要,关登录 / 搭建者不要;补固定那条日志里的固定目标也不给。""" + from app.api import runs as runs_api + + graph = querycore.prepared_graph("wf-1", card_id=CARD, metric_ids=["gmv"], inputs=INPUTS) + token = as_user("carol") + try: + projection = runs_api.run_projection(graph) + assert projection is not None + assert projection.graph(graph)["nodes"][1]["data"]["config"]["args"].get("workflow") is None + pin = {"type": "log", "node_id": None, + "data": {"code": "late_pin", "source": "门店报损", "rows": "mine", "caliber": "wf-1@1:card", + "workflow_id": "wf-1", "version": 1, "late": True, "pinned_by": "caliber_query"}} + safe = projection.event(pin)["data"] + assert safe["source"] == "门店报损" and safe["rows"] == "mine" and "caliber" not in safe + assert "workflow_id" not in safe and "version" not in safe + finally: + deps.reset_principal(token) + assert runs_api.run_projection(graph) is None, "关登录:照原样给" + + +# ========================================================================== +# 7、角色以身份为准:访问密钥 / 角色快照不一致时不放行(安全复核 3) +# ========================================================================== + + +async def test_a_key_capped_identity_is_not_raised_by_the_database_role(client): + """访问密钥认出来的身份封顶在使用者:它的用户名在库里是管理员,也不能因此被抬成放行。""" + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("rootish", "admin") + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) + key_like = Principal(username="rootish", role="user", verified=True, mode="local", via="key") + token = deps.set_principal(key_like) + try: + async with SessionLocal() as session: + assert await chat_policy.restricted_actor(session, key_like) is True + # 形参给的是名字(工具那条路拿到的就是父 Run 上记的名字)时,请求那一档更严 → 取更严的 + assert await chat_policy.restricted_actor(session, "rootish") is True + with pytest.raises(querycore.QueryCoreRefused) as caught: + await execute(asset) + finally: + deps.reset_principal(token) + assert caught.value.code == querycore.NOT_AUTHORIZED + + # 反过来:身份说自己是搭建者、库里是使用者 —— **发起前那一道**以身份为准(和 deps.restricted 同一条);但运行里 + # 记下来的只有**名字**,运行到「转抄口径」那一步时只有库里的角色可认(metrics 节点、工具路径都是这个规则), + # 所以这一次运行会在节点上失败。两条规则各自按它拿得到的那一份证据判,不互相冒充。 + await auth_env.make_user("mismatch", "user") + builder_like = Principal(username="mismatch", role="builder", verified=True, mode="local") + async with SessionLocal() as session: + assert await chat_policy.restricted_actor(session, builder_like) is False, "身份说自己是搭建者:以身份为准" + # 只给名字(工具那条路拿到的就是名字)时只有库里的角色可认:库里是使用者 → 按使用者算,不因身份那一次放行 + assert await chat_policy.restricted_actor(session, "mismatch") is True + outcome = await execute(asset, actor=builder_like) + assert outcome.status == "failed" and querycore.NOT_AUTHORIZED in str( + [p.get("message") for p in outcome.problems]), "运行里只剩名字:口径那一步按库里那一档判" + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_a_disabled_person_stays_limited_by_name(client): + """手上只有用户名时仍回库里认停用:停用的人按普通使用者算(拿不到授权就是拒)。""" + from app.db.models import User + + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("gone", "builder") + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) + async with SessionLocal() as session: + assert await chat_policy.restricted_actor(session, "gone") is False + user = (await session.execute(select(User).where(User.username == "gone"))).scalar_one() + user.disabled = True + await session.commit() + assert await chat_policy.restricted_actor(session, "gone") is True, "停用的人不按角色放行" + with pytest.raises(querycore.QueryCoreRefused) as caught: + await execute(asset, actor="gone") + assert caught.value.code == querycore.NOT_AUTHORIZED + finally: + await admin.aclose() + await auth_env.reset() + + +# ========================================================================== +# 8、手搭的转抄卡(metrics.caliber_from):运行时按同一份资产授权核(安全复核 1) +# ========================================================================== + + +def chained_graph(workflow_id: str, *, card: str = CARD) -> dict[str, Any]: + """一张自己搭的转抄卡图:拷一份源口径的取数节点,口径卡用 `caliber_from` 钉到那一版的卡。 + + 普通使用者可以在画布上(或问数据里生成的图里)这么搭:节点类型、工具都在白名单里,**口径定义本身**是从别的工作流那一版 + 读进来的——所以这一道门只能在运行时判(`engine/nodes/metrics._require_own_caliber`)。""" + import copy + + source = upload_graph() + fetch = copy.deepcopy(next(n for n in source["nodes"] if n["id"] == "sales")) + fields = next(n for n in source["nodes"] if n["id"] == "start")["data"]["config"]["fields"] + return S.chain( + S.node("start", "input", fields=copy.deepcopy(fields)), + fetch, + S.node(CARD, "metrics", caliber="转抄的合成周销售", caliber_version="v1", + caliber_from={"workflow_id": workflow_id, "workflow_version": 1, "node_id": card}), + S.node("out", "output", fields=[{"name": "答", "value": "运行结束"}])) + + +async def run_chained(who: str, workflow_id: str, *, card: str = CARD, **kw: Any) -> Any: + run = await run_manager.start(graph=chained_graph(workflow_id, card=card), input_payload=dict(INPUTS), + started_by=who, **kw) + return await _settled(run.id) + + +async def test_a_chained_card_is_refused_without_the_asset_grant(client): + """没授权:转抄卡那一步在**读定义、算数之前**失败(机器码同一条),别人的口径定义一个字都读不进来。""" + from app.engine.evidence_reader import read_sealed + + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" + await auth_env.make_user(who, "user") + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) + before = await runs_matching(started_by=who) + + row = await run_chained(who, asset["workflow_id"]) + assert row.status == "failed" and querycore.NOT_AUTHORIZED in str(row.error or ""), row.error + assert asset["workflow_id"] not in str(row.error or "") and CARD not in str(row.error or ""), row.error + sealed = await read_sealed(row.id) + assert [e for e in sealed.events if e[1] == "node.finished" and e[2] == CARD] == [], \ + "在算数之前失败:口径卡节点一次都没跑完" + assert await runs_matching(started_by=who) == before + 1, "这次运行本身是发起过的(不是发起被拒)" + + # 那一条失败事件过一遍投影(普通使用者读得到的运行事件):口径名与卡都不带出来,机器码留着 + from app.api import runs as runs_api + from app.db.models import RunEvent, Workflow + + async with SessionLocal() as session: + workflow = await session.get(Workflow, asset["workflow_id"]) + rows = list((await session.execute(select(RunEvent).where(RunEvent.run_id == row.id))).scalars()) + token = as_user(who) + try: + projection = runs_api.run_projection(row.graph) + failures = [projection.event({"type": e.type, "node_id": e.node_id, "data": e.data}) for e in rows + if e.type in runs_api.FAILURE_EVENTS] + finally: + deps.reset_principal(token) + assert failures, "这一次运行有失败事件" + dumped = json.dumps(failures, ensure_ascii=False) + assert workflow.name not in dumped, dumped + assert querycore.NOT_AUTHORIZED in dumped and "转抄的口径没有授权" not in dumped, dumped + + # 给了授权就照常读那一版的定义、算出那一版的数 + await grant_caliber(asset["workflow_id"], 1, who, "use") + ok = await run_chained(who, asset["workflow_id"]) + assert ok.status == "succeeded", ok.error + payload = json.dumps((await read_sealed(ok.id)).payload_of([CARD]) or {}, default=str) + assert str(WINDOW_SUM) in payload, payload[:400] + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_a_system_run_and_builders_are_not_judged_by_the_caliber_rule(client): + """服务端自己发起的运行(不记发起人:按需比对、口径召回、目录变化后的重算)与 builder 照旧跑得完。 + + 只有「认得出是普通使用者、又没拿到这一版的授权」才拒(上一条用例)。这一条盯住另外两档不被误伤: + 召回那批后台运行就是不带发起人的(`ledger/recall.launch(actor=None)`)。""" + admin = await auth_env.turn_on_local() + try: + builder = f"b{uuid.uuid4().hex[:8]}" + await auth_env.make_user(builder, "builder") + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) + + token = deps.set_principal(None) # 没有请求身份、运行也不记发起人:服务端自己发起的 + try: + run = await run_manager.start(graph=chained_graph(asset["workflow_id"]), input_payload=dict(INPUTS)) + system = await _settled(run.id) + finally: + deps.reset_principal(token) + assert system.status == "succeeded", system.error + + built = await run_chained(builder, asset["workflow_id"]) + assert built.status == "succeeded", built.error + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_the_chained_card_only_uses_the_pinned_version(client): + """授权是按(工作流, 版本)给的:钉住的那一版有授权才跑得成;同一张卡改钉另一版、那一版没授权照样拒。""" + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" + await auth_env.make_user(who, "user") + first = await make_workflow(graph=upload_graph()) + await publish(admin, first) # v1 + second = await add_version(first, upload_graph(include_open=True), version=2) + await publish(admin, second, version=2) # v2 成了推荐版 + await grant_caliber(first["workflow_id"], 1, who, "use") # 只给 v1 + + one = await run_chained(who, first["workflow_id"]) + assert one.status == "succeeded", one.error + + graph = chained_graph(first["workflow_id"]) + next(n for n in graph["nodes"] if n["id"] == CARD)["data"]["config"]["caliber_from"]["workflow_version"] = 2 + run = await run_manager.start(graph=graph, input_payload=dict(INPUTS), started_by=who) + other = await _settled(run.id) + assert other.status == "failed" and querycore.NOT_AUTHORIZED in str(other.error or "") + finally: + await admin.aclose() + await auth_env.reset() + + +# ========================================================================== +# 9、图与失败说法的投影:提示词、转抄卡映射、失败白话(安全复核 2) +# ========================================================================== + + +def _ask_graph(workflow_id: str) -> dict[str, Any]: + """普通使用者的图:agent 绑口径查询(提示词里照抄了 look 交回的「取数写法」)+ 一张转抄卡。""" + call = json.dumps({"workflow": workflow_id, "card": CARD, "metric_ids": ["gmv"], + "inputs": {"start": "2026-09-01", "end": "2026-10-01"}}, ensure_ascii=False) + return S.chain( + S.node("start", "input", fields=[{"name": "question"}]), + S.node("ask", "agent", prompt=f"回答问题:照这一行调 {querycore.CALIBER_QUERY} 取数(不要自己写取数 SQL):{call}", + tools=[S.tool(), querycore.CALIBER_QUERY], max_steps=4), + S.node("out", "output", fields=[{"name": "答案", "value": "{{ nodes.ask.text }}"}]), + S.node(CARD, "metrics", caliber_from={"workflow_id": workflow_id, "workflow_version": 1, "node_id": CARD, + "nodes": {"sales": "sales"}}, metrics=[]), + ) + + +def test_the_projection_redacts_prompts_and_chained_maps(): + """图上与口径有关的内部写法:提示词里的取数写法(身份的值)、转抄卡的身份映射——键、说明、inputs 的值都留着。""" + from app.api import runs as runs_api + + graph = _ask_graph("wf-1") + token = as_user("carol") + try: + projected = runs_api.run_projection(graph).graph(graph) + finally: + deps.reset_principal(token) + prompt = projected["nodes"][1]["data"]["config"]["prompt"] + assert "不要自己写取数 SQL" in prompt and '"metric_ids"' in prompt, "说明与要算的指标留着" + assert '"start": "2026-09-01"' in prompt, "要填的入口取值留着" + assert "wf-1" not in prompt, "口径身份那几个值换掉了" + assert f'"workflow": "(有授权的口径)"' in prompt and f'"card": "(有授权的口径)"' in prompt, prompt + assert projected["nodes"][3]["data"]["config"]["caliber_from"] == runs_api.CALIBER_FROM_NOTE + # 原件不动 + assert graph["nodes"][1]["data"]["config"]["prompt"].count("wf-1") == 1 + assert graph["nodes"][3]["data"]["config"]["caliber_from"]["workflow_version"] == 1 + # builder 及以上拿到的是原件 + assert runs_api.run_projection(graph) is None + + +def test_a_failure_says_it_without_the_caliber_identity(): + """失败说法的安全白话:机器码留着,口径名、版本、card 不带出来;不是口径那一档的原样给。""" + from app.api import runs as runs_api + + message = ("工具 caliber_query 执行失败:没有权限:口径「周合成-abc」v1 没有授权给你使用" + "(querycore_not_authorized)。请检查节点中填写的参数") + assert runs_api.safe_failure(message) == f"{runs_api.CALIBER_FAILED_TEXT}(querycore_not_authorized)" + assert runs_api.safe_failure("模型调用失败:接入返回了 502") is None + assert runs_api.safe_failure(None) is None + + +# ========================================================================== +# 10、普通使用者读得到的运行:失败说法与账本视图(安全复核 2、3) +# ========================================================================== + + +async def test_a_plain_user_sees_a_safe_failure_on_the_run_and_its_events(client): + """自己发起的问数据运行里口径查询失败:运行记录与事件里的说法都只留「没成功 + 机器码」。""" + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" + await auth_env.make_user(who, "user") + await _allow_chat(admin) + asset = await make_workflow(graph=upload_graph()) + await publish(admin, asset) # 不给授权:口径查询在工具那一层被拒 + graph = S.chain( + S.node("start", "input", fields=[{"name": "question"}]), + S.node("look", "tool", tool=querycore.CALIBER_QUERY, + args={"workflow": asset["workflow_id"], "card": CARD, "metric_ids": ["gmv"], "inputs": INPUTS}), + S.node("out", "output", fields=[{"name": "答", "value": "{{ nodes.look.ok }}"}])) + run = await run_manager.start(graph=graph, input_payload={}, run_class="exploratory", started_by=who, + origin_kind="chat", options={MASK_RESULTS_OPTION: True, READ_ONLY_OPTION: True}) + row = await _settled(run.id) + assert row.status == "failed" and querycore.NOT_AUTHORIZED in str(row.error or "") + + person = await auth_env.login(who) + detail = (await person.get(f"/api/runs/{run.id}")).json() + assert detail["error"] == f"按口径取数没有成功(querycore_not_authorized)", detail["error"] + events = (await person.get(f"/api/runs/{run.id}/events")).json() + dumped = json.dumps(events, ensure_ascii=False) + assert asset["workflow_id"] not in dumped and CARD not in dumped + [failed] = [e for e in events if e["type"] == "node.failed"] + assert failed["data"]["error"] == "按口径取数没有成功(querycore_not_authorized)" + [whole_run] = [e for e in events if e["type"] == "run.failed"] + assert whole_run["data"]["error"] == "按口径取数没有成功(querycore_not_authorized)", whole_run + assert whole_run["data"]["label"], "失败在哪一步(节点的叫法)留着" + # 搭建者看到的还是原话(口径名、卡、码都在) + raw = (await admin.get(f"/api/runs/{run.id}/events")).json() + [raw_failed] = [e for e in raw if e["type"] == "node.failed"] + assert asset["workflow_id"] in json.dumps(raw, ensure_ascii=False) or CARD in raw_failed["data"]["error"] + await person.aclose() + finally: + await admin.aclose() + await auth_env.reset() + + +async def matched_run(monkeypatch, who: str) -> str: + """一次与「周销售」等价、封存后比对过的运行(发起人是这个使用者):账本视图用它。""" + from app.ledger import match as ledger_match + + S.script(monkeypatch, text="本周销售额 [[v:Q1.r0.销售额]]。") + run = await run_manager.start(graph=S.explore_graph(S.EQUIVALENT), input_payload={}, run_class="exploratory", + origin_kind="canvas", started_by=who) + row = await S.wait(run.id) # 等封存(比对读的是封存范围,只等状态会偶发地读到 pending) + assert row.status == "succeeded" and row.manifest_seq is not None, row.error + await ledger_match.drain() + return row.id + + +async def test_the_ledger_view_drops_the_caliber_identity_for_a_plain_user(client, monkeypatch): + """普通使用者的口径账本:内部身份(工作流 id / 版本 / 哈希 / 卡节点 id)不出去,人读的那一套一个字不动。""" + admin = await auth_env.turn_on_local() + try: + who = f"u{uuid.uuid4().hex[:8]}" + await auth_env.make_user(who, "user") + workflow_id = await S.publish() + run_id = await matched_run(monkeypatch, who) + + person = await auth_env.login(who) + res = await person.get(f"/api/runs/{run_id}/ledger") + assert res.status_code == 200, res.text + body = res.json() + assert body["state"] == "matched" + dumped = json.dumps(body, ensure_ascii=False) + assert workflow_id not in dumped, "工作流 id 不出去(这一次的出具被拒:只说明,不给身份)" + for key in ("workflow_id", "graph_hash", "closure_hash", "selection_hash", "execution_hash"): + assert f'"{key}"' not in dumped, key + assert body["actions"] and body["actions"][0]["available"] is False, body["actions"] + # 人读的:口径名、级别叫法、指标标签与绑定、每条查询的结果、证据关系 + [caliber] = body["calibers"] + assert caliber["workflow_name"] == "周销售" and caliber["level_text"] == "受管" and caliber["caliber"] + [label] = body["reports"]["write"]["labels"].values() + assert label["kind"] == "caliber" and label["workflow_name"] == "周销售" and label["binding"] + assert "node_id" not in label and "version" not in label + [query] = body["queries"] + assert query["node_id"] and query["artifact"] and query["status"] == "proven", "证据关系留着" + assert "node_id" not in query["candidates"][0] + assert [a["kind"] for a in body["actions"]] == ["issue"] and body["whole"]["equivalent"] is True + + # 搭建者拿到的是原件:工作流 id、版本、哈希、卡节点 id 都在 + raw = (await admin.get(f"/api/runs/{run_id}/ledger")).json() + raw_dumped = json.dumps(raw, ensure_ascii=False) + assert workflow_id in raw_dumped and '"graph_hash"' in raw_dumped + assert "node_id" in raw["reports"]["write"]["labels"][next(iter(raw["reports"]["write"]["labels"]))] + + # 有权出具的人(应用授权把这一版固定给它):出具那一项要带着身份去发请求——只有**确实给它做**的那一项带 + await grant_caliber(workflow_id, 1, who, "use") + allowed = (await person.get(f"/api/runs/{run_id}/ledger")).json() + [action] = allowed["actions"] + assert action["available"] is True and action["workflow_id"] == workflow_id and action["version"] == 1 + assert allowed["calibers"][0].get("workflow_id") is None, "别处照旧不给身份" + assert allowed["reports"]["write"]["labels"][next(iter(allowed["reports"]["write"]["labels"]))].get("version") is None + + # 证据片段 / 报告导出读的是同一份标签(ledger/view.report_labels):同一条投影 + from app.api.evidence import _sealed + from app.ledger.view import report_labels + + sealed = await _sealed(run_id) + token = as_user(who) + try: + labels = (await report_labels(sealed, "write"))["labels"] + finally: + deps.reset_principal(token) + [label] = labels.values() + assert label["kind"] == "caliber" and label["workflow_name"] == "周销售" + assert "workflow_id" not in label and "node_id" not in label and "version" not in label + await person.aclose() + finally: + await admin.aclose() + await auth_env.reset() diff --git a/backend/tests/test_run_timing.py b/backend/tests/test_run_timing.py index 8295826d..f4a5bb84 100644 --- a/backend/tests/test_run_timing.py +++ b/backend/tests/test_run_timing.py @@ -8,7 +8,9 @@ - started_at 只在第一次开始时写; - duration_ms(= active_ms)是各段执行时长之和; - wall_ms 是从第一次开始到结束的墙钟;wait_ms 是等人审批的总时长; -- 三者随 run.finished / run.failed / run.cancelled 的 timing 一起发出。 +- queue_ms(K13)是各段等并发名额的总时长:那一截在 started_at 之前,既不在 active 里也不算进 wall, + 单独记,和等人审批的 wait_ms 是两回事; +- 四者随 run.finished / run.failed / run.cancelled 的 timing 一起发出。 """ from __future__ import annotations @@ -120,7 +122,10 @@ async def test_resumed_run_keeps_its_start_and_sums_every_segment(slow_transform finished = next(e for e in await _events(run.id) if e.type == "run.finished") assert finished.data["timing"] == { "wall_ms": usage["wall_ms"], "active_ms": usage["active_ms"], "wait_ms": usage["wait_ms"], + "queue_ms": usage["queue_ms"], } + # 没人抢名额时 queue_ms 只剩「要名额到拿到名额」那一下的开销(几毫秒);绝不能拿等人那 0.6 秒冒充 + assert 0 <= usage["queue_ms"] < WAIT * 1000 / 2, usage async def test_bookkeeping_after_the_pause_is_not_counted_twice(slow_transforms, monkeypatch): @@ -186,7 +191,7 @@ async def test_continued_run_keeps_its_start_and_sums_every_segment(fails_once): assert failed.usage["duration_ms"] >= SEGMENT * 1000 * 0.9 failed_ev = next(e for e in await _events(run.id) if e.type == "run.failed") - assert set(failed_ev.data["timing"]) == {"wall_ms", "active_ms", "wait_ms"} + assert set(failed_ev.data["timing"]) == {"wall_ms", "active_ms", "wait_ms", "queue_ms"} assert failed_ev.data["node_id"] == "flaky" await run_manager.continue_failed(run.id) @@ -210,7 +215,7 @@ async def test_cancel_reports_timing_too(slow_transforms): assert await run_manager.cancel(run.id) await _wait(run.id, ("cancelled",)) cancelled = next(e for e in await _events(run.id) if e.type == "run.cancelled") - assert set(cancelled.data["timing"]) == {"wall_ms", "active_ms", "wait_ms"} + assert set(cancelled.data["timing"]) == {"wall_ms", "active_ms", "wait_ms", "queue_ms"} assert cancelled.data["timing"]["active_ms"] > 0 diff --git a/backend/tests/test_runs_cancel_waiting.py b/backend/tests/test_runs_cancel_waiting.py index 91b07dde..15d6e3e3 100644 --- a/backend/tests/test_runs_cancel_waiting.py +++ b/backend/tests/test_runs_cancel_waiting.py @@ -100,7 +100,7 @@ async def test_a_run_waiting_for_approval_can_be_abandoned(client): events = await _events(run_id) last = events[-1] assert last.type == "run.cancelled", [e.type for e in events[-3:]] - assert set(last.data["timing"]) == {"wall_ms", "active_ms", "wait_ms"} + assert set(last.data["timing"]) == {"wall_ms", "active_ms", "wait_ms", "queue_ms"} assert last.data.get("actor") == "审核员甲" verified = (await client.get(f"/api/runs/{run_id}/verify")).json() assert verified["sealed"] and verified["ok"], verified diff --git a/backend/tests/test_sql_parameter_integrity.py b/backend/tests/test_sql_parameter_integrity.py new file mode 100644 index 00000000..8c64c8d8 --- /dev/null +++ b/backend/tests/test_sql_parameter_integrity.py @@ -0,0 +1,633 @@ +"""SQL 模板参数完整性(开工任务书 v3 · K01,§4.4):ledger/params 一套语义,各入口同一结果。 + +- 认模板里的参数(引号里的字 / 裸写 / 注释里)、未声明的字段、缺值的字段(含声明成可选、又没有缺省值的);写在表名列名 + 里、认不出写法的照实拒(单元一层,函数返回机器码); +- 组合式问数拷进来的取数节点:值在拷的时候渲染进 SQL(只渲染这一次),节点上写一份与**这条渲染好的 args** 绑定的 + 参数契约:跑一次真实的问数运行,断言**实际发给数据库的那条 SQL** 就带着值里的 {{ }} 文本(字面量,不再被解释); +- 契约与它注解的语句绑定哈希:复制走、改过 SQL 之后契约作废,那个节点回退成普通模板(正常渲染、正常判参数,带 {{ }} + 的语句绝不原样发出去); +- 派生图(口径探针)同样:入口参数值里的 {{ }} 是字面量,各入口同值同语义; +- 缺参数(声明成可选、没有缺省值;开放入口里显式传了空串)、未声明参数:**零 SQL**——数一下 run_query 被调了几次,就是 0; + 显式空串算没给,作者声明的 `default=""` 才算声明式省略(两条都有真实运行反例); +- 查询快照记源模板哈希、规范化输入哈希、参数契约与写在哪儿,承载方式照实写 inline_text(不假装驱动绑定); +- 对账图里「这次的取数」放的是执行过的语句:运行时的模板渲染不再碰它。 + +数据是虚构店铺库(tests/ledger_samples.py)。 +""" +from __future__ import annotations + +import hashlib + +import pytest +from sqlalchemy import select + +from app.db.base import SessionLocal +from app.db.models import Artifact +from app.engine.runner import run_manager +from app.ledger import compose, derive, params +from app.ledger import match as ledger_match +from app.look.calibers import CaliberKind +from tests import ledger_samples as S + +TEMPLATE = S.TEMPLATE + + +@pytest.fixture(autouse=True) +async def engine_up(tmp_path): + await run_manager.setup() + await S.fresh_source(tmp_path / "shop.db") + yield + await ledger_match.drain() + await run_manager.shutdown() + + +@pytest.fixture +def executed(monkeypatch) -> list[str]: + """这一次测试里真正发给数据库的语句(内联渲染之后的那一条),按先后。""" + from app.tools import datasource + + seen: list[str] = [] + real = datasource.run_query + + async def spy(source, sql, **kw): + seen.append(sql) + return await real(source, sql, **kw) + + monkeypatch.setattr(datasource, "run_query", spy) + return seen + + +async def query_snapshots(run_id: str) -> list[dict]: + """这次运行落下的查询快照内容(按工件 id)。""" + from app.core.artifact_store import load + from app.data.catalog import QUERY_SNAPSHOT_KIND + + async with SessionLocal() as session: + rows = (await session.execute(select(Artifact.id).where( + Artifact.run_id == run_id, Artifact.kind == QUERY_SNAPSHOT_KIND))).scalars().all() + return [payload for payload in (load(rid) for rid in rows) if isinstance(payload, dict)] + + +# ========================================================================== +# 认得模板里的参数(单元一层:机器码 + 写在哪儿) +# ========================================================================== + + +def test_parameters_are_read_where_they_are_written(): + slots = params.slots_of("SELECT * FROM t WHERE d >= '{{ input.start }}' AND n > {{ input.n }} " + "AND r = '{{ input.region | trim }}' -- {{ input.note }}") + assert [(s.field, s.context, s.filters) for s in slots] == [ + ("start", "quoted", ()), ("n", "bare", ()), ("region", "quoted", ("trim",)), ("note", "comment", ())] + + +@pytest.mark.parametrize(("sql", "words"), [ + ('SELECT * FROM "{{ input.table }}"', "表名或列名"), + ("SELECT {{ vars.pick }} FROM t", "运行时才有的变量"), + ("SELECT {{ file_text(input.f) }} FROM t", "附件"), + ("SELECT * FROM t WHERE a = '{{ input.x | upper }}'", "upper"), + ("SELECT {{ input }} FROM t", "认不出"), +]) +def test_unreadable_parameter_writings_are_refused(sql, words): + problems = params.check_template(sql, fields={"x": {"name": "x"}}, values={"x": "v"}) + assert [p.code for p in problems] == [params.UNSUPPORTED] and words in problems[0].message + + +def test_undeclared_and_missing_are_two_different_findings(): + fields = {"start": {"name": "start", "required": True}} + problems = params.check_template("SELECT '{{ input.start }}', '{{ input.nope }}'", fields=fields, values={}, + where="口径「周销售」的入口") + assert [(p.code, p.name) for p in problems] == [(params.MISSING, "start"), (params.UNDECLARED, "nope")] + assert "(undeclared_parameter)" in problems[1].message and "nope" in problems[1].message + assert "不能当空串用(missing_parameter)" in problems[0].message + # 模板和声明对得上(还没到判值的那一步):读一版口径时只判这一层 + assert params.check_template("SELECT '{{ input.start }}'", fields=fields) == [] + + +def test_an_optional_parameter_without_a_default_is_missing_not_empty(): + fields = {"store": {"name": "store"}} + [problem] = params.check_template("SELECT * FROM t WHERE s = '{{ input.store }}'", fields=fields, values={}) + assert problem.code == params.MISSING and problem.name == "store" + # 声明了缺省值(含 `""`:作者写的就是空值不过滤)就不算缺 + assert params.check_template("SELECT * FROM t WHERE s = '{{ input.store }}'", + fields={"store": {"name": "store", "default": ""}}, values={}) == [] + assert params.check_template("SELECT * FROM t WHERE s = '{{ input.store }}'", + fields={"store": {"name": "store", "default": "all"}}, values={}) == [] + + +@pytest.mark.parametrize(("sql", "value", "code", "words"), [ + ("SELECT * FROM t WHERE s = '{{ input.x }}'", "O'Brien", params.LITERAL, "值里不能有引号"), + ("SELECT * FROM t WHERE s = '{{ input.x }}'", "a\\b", params.LITERAL, "反斜杠"), + ("SELECT * FROM t WHERE n > {{ input.x }}", "1 OR 1=1", params.LITERAL, "只能是数"), + ("SELECT * FROM t -- {{ input.x }}", "*/ DROP TABLE t", params.LITERAL, "注释"), +]) +def test_values_the_inline_adapter_cannot_carry_are_refused(sql, value, code, words): + fields = {"x": {"name": "x"}} + [problem] = params.check_template(sql, fields=fields, values={"x": value}) + assert problem.code == code and words in problem.message + + +def test_one_field_with_two_slots_reports_one_problem(): + """同一个字段写了两处槽位(引号里一处、裸写一处):承载不了只报一条,不重复报。""" + [problem] = params.check_template("SELECT '{{ input.x }}' AS a, {{ input.x }} AS b", + fields={"x": {"name": "x"}}, values={"x": "O'Brien"}) + assert (problem.code, problem.name) == (params.LITERAL, "x") + + +@pytest.mark.parametrize(("sql", "fields", "dynamic"), [ + ("SELECT '{{ input.store }}'", ("store",), ()), + ("SELECT '{{ input['store'] }}'", ("store",), ()), + ('SELECT {{ input["store"] }}', ("store",), ()), + ("SELECT {{ input[0] }}", ("0",), ()), + ("SELECT {{ input.rows[0].name }}", ("rows",), ()), + ("SELECT '{{ input['store'] | trim }}'", ("store",), ()), + ("SELECT {{ file_text(input['附件']) }}", ("附件",), ()), + ("SELECT {{ input }}", (), ("input",)), + ("SELECT '{{ input['a.b'] }}'", (), ("input['a.b']",)), + ("SELECT {{ input[a[b]] }}", (), ("input[a[b]]",)), + ("SELECT {{ input x }}", (), ("input x",)), + ("SELECT {{ inputs.x }}, {{ input_value }}", (), ()), + ("SELECT {{ vars.region }}, {{ nodes.q.text }}", (), ()), +]) +def test_input_references_follow_the_same_path_walk_as_resolve_path(sql, fields, dynamic): + """运行时认的入口引用和 engine/expressions.resolve_path 一个走法:点号与合法下标都算字段引用(取第一层), + 认不出的写法(会渲染成空串)单独交出来——vars./nodes. 不归这一趟管。""" + assert params.input_refs(sql) == fields + assert params.dynamic_input_writings(sql) == dynamic + assert params.mentions_input(sql) is bool(fields or dynamic) + + +def test_declared_types_are_normalized_without_looking_at_the_value(): + assert params.field_type({"type": "integer"}) == params.field_type({"type": "int"}) == "integer" + assert params.field_type({}) == params.field_type({"type": "nonsense"}) == "string" + assert params.value_kind(3) == "number" and params.value_kind("3") == "text" and params.value_kind(None) == "null" + + +# ========================================================================== +# 组合式问数:值只渲染一次(E03) +# ========================================================================== + + +async def composed_answer_graph(workflow_id: str, inputs: dict) -> dict: + """把口径拷进问数据的图(同 tests/test_ledger_compose.py 的做法,这里直接走 compose):args 是字面语句 + 参数契约。""" + from app.ledger import compose + + async with SessionLocal() as session: + kind = await CaliberKind.load(session, compose=True) + made = compose.Composer(list(kind.options)).compose( + {"op": "use_caliber", "id": "c1", "workflow_id": workflow_id, "version": 1, "metrics": ["gmv"], + "inputs": inputs}, taken=set()) + return S.chain(S.node("start", "input", fields=[{"name": "question"}]), *made.nodes, + S.node("write", "report", instructions="写周销售"), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.write.text }}"}])) + + +async def test_a_value_that_looks_like_a_template_stays_literal_in_the_executed_sql(monkeypatch, executed): + """E03:参数值里的 {{ }} 是数据,不被二次解释。 + + 这里挑的是**在答数图里取得出值**的那一种写法({{ vars.question }} 指向入口字段):万一运行时又渲染一遍,值会被换成 + 问题的原文,SQL 就被数据改掉了——正是这条反例要拦住的那条路。""" + wf = await S.publish() + graph = await composed_answer_graph(wf, {"start": "{{ vars.question }}", "end": "2026-09-08"}) + S.script(monkeypatch, "本周销售额 [[m:gmv]]。") + run = await run_manager.start(graph=graph, input_payload={"question": "九月第一周卖了多少"}, origin_kind="chat") + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + [sql] = executed + assert sql == TEMPLATE.replace("{{ input.start }}", "{{ vars.question }}").replace("{{ input.end }}", "2026-09-08") + assert "'{{ vars.question }}'" in sql and "九月第一周卖了多少" not in sql + + +async def test_a_value_naming_a_variable_that_does_not_exist_runs_as_a_literal(monkeypatch, executed): + """反例的另一半:值里写的是图里根本没有的变量({{ vars.region }})——照样按字面量跑,不判成「没人产出的引用」。 + + 画布上那条变量校验(engine/variables)会把节点配置里带 {{ }} 的字当成活引用;组合式问数拷进来的取数节点是服务端 + 渲染好的**数据**,它不该被那条规则拦下——否则「值里恰好有几个花括号」就等于这张图跑不了。""" + wf = await S.publish() + graph = await composed_answer_graph(wf, {"start": "{{ vars.region }}", "end": "2026-09-08"}) + S.script(monkeypatch, "本周销售额 [[m:gmv]]。") + run = await run_manager.start(graph=graph, input_payload={"question": "九月第一周卖了多少"}, origin_kind="chat") + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + [sql] = executed + assert "'{{ vars.region }}'" in sql and "'2026-09-08'" in sql + + +async def test_a_copied_node_edited_back_into_a_template_renders_normally(monkeypatch, executed): + """复制一个拷进来的取数节点、把 SQL 改回普通模板:契约作废,回退正常渲染——只渲染一次,不发带 {{ }} 的语句。""" + wf = await S.publish() + graph = await composed_answer_graph(wf, {"start": "2026-09-01", "end": "2026-09-08"}) + fetch = next(n for n in graph["nodes"] if n["id"] == "c1_fetch") + assert params.literal_keys(fetch["data"]["config"], "tool") == ("args",) + fetch["data"]["config"]["args"]["sql"] += " AND '{{ input.question }}' <> ''" + assert params.literal_keys(fetch["data"]["config"], "tool") == () + S.script(monkeypatch, "本周销售额 [[m:gmv]]。") + run = await run_manager.start(graph=graph, input_payload={"question": "九月第一周卖了多少"}, origin_kind="chat") + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + [sql] = executed + assert "'九月第一周卖了多少'" in sql and "{{" not in sql + + +async def test_a_copied_node_with_an_incomplete_edit_sends_no_sql(monkeypatch, executed): + """复制后改过的 SQL 引用了入口声明过、这次没给的参数:运行时按同一套参数完整性拒,零 SQL。 + + 契约在这里也帮不上忙(哈希对不上就当没写):走的是普通模板那条路——渲染前判缺参数,绝不把带 {{ }} 的语句发出去。""" + wf = await S.publish() + graph = await composed_answer_graph(wf, {"start": "2026-09-01", "end": "2026-09-08"}) + start = next(n for n in graph["nodes"] if n["id"] == "start") + start["data"]["config"]["fields"].append({"name": "store"}) # 可选、没有缺省值 + fetch = next(n for n in graph["nodes"] if n["id"] == "c1_fetch") + fetch["data"]["config"]["args"]["sql"] += " AND region = '{{ input.store }}'" + assert params.literal_keys(fetch["data"]["config"], "tool") == () + S.script(monkeypatch, "本周销售额 [[m:gmv]]。") + run = await run_manager.start(graph=graph, input_payload={"question": "九月第一周卖了多少"}, origin_kind="chat") + row = await S.wait(run.id) + assert row.status == "failed" and "store" in row.error and "missing_parameter" in row.error, row.error + assert executed == [] + + +async def test_the_probe_path_renders_a_template_like_value_once_too(executed): + """派生图(口径探针、试跑走的就是它)同值同语义:入口值里的 {{ }} 也是字面量。""" + wf = await S.publish() + async with SessionLocal() as session: + pinned = await derive.load_pinned(session, wf, 1, "card") + run = await run_manager.start(graph=derive.caliber_probe(pinned).graph, + input_payload={"start": "{{ vars.region }}", "end": "2026-09-08"}) + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + [sql] = executed + assert "'{{ vars.region }}'" in sql and "'2026-09-08'" in sql + + +async def test_the_query_snapshot_records_the_template_hash_types_and_no_fake_binding(monkeypatch, executed): + """快照记源模板哈希、规范化输入哈希、参数契约与写在哪儿;承载方式照实写内联(不假装驱动绑定)。""" + wf = await S.publish() + graph = await composed_answer_graph(wf, {"start": "2026-09-01", "end": "2026-09-08"}) + S.script(monkeypatch, "本周销售额 [[m:gmv]]。") + run = await run_manager.start(graph=graph, input_payload={"question": "九月第一周卖了多少"}, origin_kind="chat") + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + [payload] = await query_snapshots(run.id) + material = payload["parameters"] + assert material["adapter"] == params.ADAPTER == "inline_text" + assert material["binding"] == "values_in_statement" + # 源模板正文不在节点上(engine/variables 会扫节点配置里的 {{ }}):记哈希 + 那一版取数节点的固定引用, + # 模板本体按引用从不可变版本快照还原,哈希核对 + assert material["template_hash"] == hashlib.sha256(TEMPLATE.encode("utf-8")).hexdigest() + assert len(material["inputs_hash"]) == 64 and "template" not in material + assert [(p["name"], p["kind"], p["declared"], p["slot"]) for p in material["parameters"]] == [ + ("start", "text", "string", "quoted"), ("end", "text", "string", "quoted")] + # 契约跟着材料一起记;绑定值不另存一份:它就是内联进实际语句里的那些字,实际语句本身在快照里 + assert [d["name"] for d in material["declared"]] == ["start", "end", "store"] + assert set(material) == {"adapter", "binding", "template_hash", "inputs_hash", "declared", "parameters", + "source"} + assert payload["sql"] == TEMPLATE.replace("{{ input.start }}", "2026-09-01").replace("{{ input.end }}", + "2026-09-08") + assert material["source"]["node_id"] == "fetch" and material["source"]["workflow_version"] == 1 + + +# ========================================================================== +# 缺参数、未声明参数:零 SQL(E04) +# ========================================================================== + + +def optional_field_graph(sql: str, fields: list[dict]) -> dict: + graph = S.caliber_graph(sql=sql) + graph["nodes"][0]["data"]["config"]["fields"] = fields + return graph + + +async def test_a_missing_optional_parameter_sends_no_sql(executed): + """可选、没有缺省值的参数这次没给:不发 SQL,运行说清是哪个参数(以前渲染成空串照发)。""" + sql = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' AND region = '{{ input.store }}' " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") + graph = optional_field_graph(sql, [{"name": "start", "required": True}, {"name": "end", "required": True}, + {"name": "store"}]) + wf = await S.publish(graph=graph) + async with SessionLocal() as session: + pinned = await derive.load_pinned(session, wf, 1, "card") + run = await run_manager.start(graph=derive.caliber_probe(pinned).graph, + input_payload={"start": "2026-09-01", "end": "2026-09-08"}) + row = await S.wait(run.id) + assert row.status == "failed" and "store" in row.error and "missing_parameter" in row.error, row.error + assert executed == [] and await query_snapshots(run.id) == [] + + +async def test_a_plain_canvas_query_with_a_missing_optional_parameter_sends_no_sql(executed): + """普通画布上的一条取数:参数声明成可选、没有缺省值、这次没给——不发 SQL(以前渲染成空串照发)。""" + graph = S.chain(S.node("start", "input", fields=[{"name": "start", "required": True}, + {"name": "store"}]), + S.node("q", "tool", tool=S.tool(), + args={"sql": "SELECT COUNT(*) AS n FROM orders WHERE region = '{{ input.store }}' " + "AND paid_at >= '{{ input.start }}'"}), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.q.text }}"}])) + run = await run_manager.start(graph=graph, input_payload={"start": "2026-09-01"}) + row = await S.wait(run.id) + assert row.status == "failed" and "store" in row.error and "missing_parameter" in row.error, row.error + assert executed == [] and await query_snapshots(run.id) == [] + + +async def test_an_undeclared_parameter_cannot_be_composed_or_derived(): + """模板引用了入口没声明的字段:读这一版(派生、组合)时就拒,机器码 undeclared_parameter。""" + graph = optional_field_graph("SELECT SUM(amount) AS gmv FROM orders WHERE region = '{{ input.nope }}'", + [{"name": "start", "required": True}, {"name": "end", "required": True}]) + wf = await S.publish(graph=graph) + async with SessionLocal() as session: + with pytest.raises(derive.NotDerivable) as caught: + await derive.load_pinned(session, wf, 1, "card") + assert caught.value.code == derive.UNDECLARED_PARAMETER and "nope" in caught.value.message + assert "undeclared_parameter" in caught.value.message + kind = await CaliberKind.load(session, compose=True) + [option] = [o for o in kind.options if o.workflow_id == wf] + assert not option.composable and "undeclared_parameter" in option.reason + + +async def test_a_query_referencing_a_parameter_nobody_declares_sends_no_sql(executed): + """取数 SQL 引用了这次运行没有的参数:不发 SQL,说清是哪个参数。 + + 入口一个字段都没声明时(开放入口)engine/variables 不会拦这种引用——运行到取数这一步由参数完整性拦,以前渲染成 + 空串照发。入口声明了字段的图更早就会被画布校验拦下(那是另一道,见下一条)。""" + graph = S.chain(S.node("start", "input"), + S.node("q", "tool", tool=S.tool(), + args={"sql": "SELECT COUNT(*) AS n FROM orders WHERE region = '{{ input.store }}'"}), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.q.text }}"}])) + run = await run_manager.start(graph=graph, input_payload={"question": "有多少单"}) + row = await S.wait(run.id) + assert row.status == "failed" and "store" in row.error and "undeclared_parameter" in row.error, row.error + assert executed == [] and await query_snapshots(run.id) == [] + + +async def test_a_value_that_the_run_provides_is_enough_even_without_a_declared_field(executed): + """入口没声明字段、值由发起时传进来(开放入口):照常发出 SQL——判断看的是「这次有没有值」,不是只认声明。 + + 这是画布上很常见的写法(入口节点只写「开始」,参数由发起时传),拦掉它会把跑得好的图判成参数不完整。""" + graph = S.chain(S.node("start", "input"), + S.node("q", "tool", tool=S.tool(), + args={"sql": "SELECT COUNT(*) AS n FROM orders WHERE paid_at >= '{{ input.start }}'"}), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.q.text }}"}])) + run = await run_manager.start(graph=graph, input_payload={"start": "2026-09-01"}) + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + assert executed == ["SELECT COUNT(*) AS n FROM orders WHERE paid_at >= '2026-09-01'"] + + +async def test_an_open_entry_with_an_explicit_empty_string_sends_no_sql(executed): + """开放入口(入口节点一个字段都没声明、键由发起时传)传来空串:算没给,不发 SQL。 + + 空串不是值,是省略——和入口收值(params.provided)同一套,也和「声明了 default="" 才算声明式省略」同一套。以前只认 + None,这种图会渲染成 `AND region = ''` 发出去;作者要表达「空值不过滤」,得把字段声明出来并写 `default=""`(下一条用例)。""" + graph = S.chain(S.node("start", "input"), + S.node("q", "tool", tool=S.tool(), + args={"sql": "SELECT COUNT(*) AS n FROM orders WHERE region = '{{ input.store }}'"}), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.q.text }}"}])) + run = await run_manager.start(graph=graph, input_payload={"store": ""}) + row = await S.wait(run.id) + assert row.status == "failed" and "store" in row.error and "missing_parameter" in row.error, row.error + assert executed == [] and await query_snapshots(run.id) == [] + + +async def test_a_declared_empty_default_still_runs_in_an_open_entry(executed): + """作者把字段声明出来、写 `default=""`:那是声明的省略规则,照跑,空串不是「没给」。""" + graph = S.chain(S.node("start", "input", fields=[{"name": "store", "default": ""}]), + S.node("q", "tool", tool=S.tool(), + args={"sql": "SELECT COUNT(*) AS n FROM orders WHERE ('{{ input.store }}' = '' " + "OR region = '{{ input.store }}')"}), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.q.text }}"}])) + run = await run_manager.start(graph=graph, input_payload={}) + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + [sql] = executed + assert "{{" not in sql and "('' = ''" in sql + + +async def test_an_executed_statement_carried_into_a_graph_is_not_templated_again(executed): + """对账里「这次的取数」:放进去的是执行过的语句,运行时不再当模板解释一遍。 + + 语句文本里挑了在答数图里取得出值的写法({{ vars.question }}):真的被再渲染一次的话,这条 SQL 就变成别的语句了。""" + text = "SELECT SUM(amount) AS gmv FROM orders WHERE region = '{{ vars.question }}' AND id > 1" + block = derive.ours_block(text, S.tool()) + assert params.mode_of(block.nodes[0]["data"]["config"]) == params.LITERAL_ARGS + graph = S.chain(S.node("start", "input", fields=[{"name": "question"}]), + block.nodes[0], + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.ours_q1.text }}"}])) + run = await run_manager.start(graph=graph, input_payload={"question": "九月第一周"}) + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + assert executed == [text] + + +async def test_a_bracket_reference_without_a_value_sends_no_sql(executed): + """`{{ input['store'] }}`(下标写法、SQL 里还嵌着引号)没给值:一样不发 SQL。 + + 运行时的兜底以前只认 `{{ input.字段 }}`,这种写法认不出来 → 渲染成 `''`,发出一条 `AND region = ''`。""" + graph = S.chain(S.node("start", "input", fields=[{"name": "store"}]), + S.node("q", "tool", tool=S.tool(), + args={"sql": "SELECT COUNT(*) AS n FROM orders WHERE region = '{{ input['store'] }}'"}), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.q.text }}"}])) + run = await run_manager.start(graph=graph, input_payload={"store": ""}) + row = await S.wait(run.id) + assert row.status == "failed" and "store" in row.error and "missing_parameter" in row.error, row.error + assert executed == [] and await query_snapshots(run.id) == [] + + +async def test_a_bracket_reference_with_a_value_renders_and_runs(executed): + """`{{ input['store'] }}` 正常给值:照常渲染进 SQL 发出去(不是拒绝一切下标写法)。""" + graph = S.chain(S.node("start", "input", fields=[{"name": "store"}]), + S.node("q", "tool", tool=S.tool(), + args={"sql": "SELECT COUNT(*) AS n FROM orders WHERE region = '{{ input['store'] }}'"}), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.q.text }}"}])) + run = await run_manager.start(graph=graph, input_payload={"store": "east"}) + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + assert executed == ["SELECT COUNT(*) AS n FROM orders WHERE region = 'east'"] + + +async def test_a_bracket_reference_uses_the_declared_default(executed): + """`{{ input['store'] }}` 配声明缺省值:没给值时按入口那套补上,渲染进去的是缺省值。""" + graph = S.chain(S.node("start", "input", fields=[{"name": "store", "default": "east"}]), + S.node("q", "tool", tool=S.tool(), + args={"sql": 'SELECT COUNT(*) AS n FROM orders WHERE region = \'{{ input["store"] }}\''}), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.q.text }}"}])) + run = await run_manager.start(graph=graph, input_payload={}) + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + assert executed == ["SELECT COUNT(*) AS n FROM orders WHERE region = 'east'"] + + +@pytest.mark.parametrize("sql", ["SELECT COUNT(*) AS n FROM orders WHERE region = '{{ input }}'", + "SELECT COUNT(*) AS n FROM orders WHERE region = '{{ input['a.b'] }}'", + "SELECT COUNT(*) AS n FROM orders WHERE region = '{{ input[a[b]] }}'"]) +async def test_an_unreadable_input_writing_sends_no_sql(executed, sql): + """认不出取哪个字段的入口写法(光秃秃的 `{{ input }}`、下标里带点/套中括号):明确拒,零 SQL。 + + 这些写法 resolve_path 取不到值 → 渲染成空串;当「没引用参数」放过去就等于发出一条条件被抹掉的查询。""" + graph = S.chain(S.node("start", "input", fields=[{"name": "question"}]), + S.node("q", "tool", tool=S.tool(), args={"sql": sql}), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.q.text }}"}])) + run = await run_manager.start(graph=graph, input_payload={"question": "有多少单"}) + row = await S.wait(run.id) + assert row.status == "failed" and "unsupported_parameter" in row.error, row.error + assert "看不出取的是哪个字段" in row.error + assert executed == [] and await query_snapshots(run.id) == [] + + +async def test_vars_and_nodes_are_left_alone_in_a_canvas_query(executed): + """普通模板照旧:取数 SQL 引用 vars./nodes. 不受这一趟影响(照常渲染后发出去)。""" + graph = S.chain(S.node("start", "input"), + S.node("pick", "transform", mode="expression", expression="'east'", assign_to="region"), + S.node("q", "tool", tool=S.tool(), + args={"sql": "SELECT COUNT(*) AS n FROM orders WHERE region = '{{ vars.region }}'"}), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.q.text }}"}])) + run = await run_manager.start(graph=graph, input_payload={}) + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + assert executed == ["SELECT COUNT(*) AS n FROM orders WHERE region = 'east'"] + + +# ========================================================================== +# 可复用的接口(试跑等入口接线用) +# ========================================================================== + + +def test_resolve_prefers_explicit_values_then_declared_defaults(): + """共享层定这一次的值:显式给的(含 0——0 是值)优先,否则用声明的缺省值(含 0 与空串);没缺省值的照旧缺。""" + fields = [{"name": "region", "default": "east"}, {"name": "min", "default": 0}, + {"name": "note", "default": ""}, {"name": "start"}] + assert params.resolve(fields, {"start": "2026-09-01"}) == { + "region": "east", "min": 0, "note": "", "start": "2026-09-01"} + assert params.resolve(fields, {"region": "west", "min": 5, "note": "x", "start": "s"}) == { + "region": "west", "min": 5, "note": "x", "start": "s"} + # 显式空串算没给:回到声明的缺省值;没声明缺省值的(start)不只是空串问题——它压根没值,不在这份里 + assert params.resolve(fields, {"region": "", "min": "", "note": "", "start": ""}) == { + "region": "east", "min": 0, "note": ""} + + +def test_plan_renders_the_declared_default_instead_of_an_empty_string(): + """声明了缺省值、调用方没给:渲染进去的必须是那个缺省值(以前 plan 拿原始 values 渲染,声明了却渲染成空)。""" + template = ("SELECT * FROM orders WHERE region = '{{ input.region }}' AND amount > {{ input.min }} " + "AND note = '{{ input.note }}'") + fields = [{"name": "region", "default": "east"}, {"name": "min", "default": 0}, {"name": "note", "default": ""}] + out = params.plan(template, fields=fields, values={}) + assert "'east'" in out.statement and "amount > 0" in out.statement and "note = ''" in out.statement + assert "{{" not in out.statement + # 检查、渲染、材料里的输入哈希用的是同一份 resolved values:显式给同样的值 → 同一份材料 + same = params.plan(template, fields=fields, values={"region": "east", "min": 0, "note": ""}) + assert same.material["inputs_hash"] == out.material["inputs_hash"] + assert [p["kind"] for p in out.material["parameters"]] == ["text", "number", "text"] + # 覆盖声明:显式给的值优先 + override = params.plan(template, fields=fields, values={"region": "west", "min": 10, "note": "x"}) + assert "'west'" in override.statement and "amount > 10" in override.statement + assert override.material["inputs_hash"] != out.material["inputs_hash"] + + +@pytest.mark.parametrize("values", [{}, {"region": ""}, {"region": None}]) +def test_plan_without_a_declared_default_still_reports_missing(values): + """没有声明的缺省值:没给、给了空串、给了 None 都是缺参数(空串不是值)。""" + with pytest.raises(params.ParameterRefused) as caught: + params.plan("SELECT * FROM orders WHERE region = '{{ input.region }}'", + fields=[{"name": "region"}], values=values) + assert caught.value.code == params.MISSING and caught.value.problems[0].name == "region" + + +def test_plan_renders_once_and_carries_the_snapshot_material(): + out = params.plan(TEMPLATE, fields=[{"name": "start", "required": True, "type": "date"}, + {"name": "end", "required": True, "type": "date"}], + values={"start": "{{ vars.x }}", "end": "2026-09-08"}) + assert "'{{ vars.x }}'" in out.statement + assert out.material["parameters"][0]["declared"] == "date" + with pytest.raises(params.ParameterRefused) as caught: + params.plan(TEMPLATE, fields=[{"name": "start", "required": True}, {"name": "end", "required": True}], + values={"start": "2026-09-01"}) + assert caught.value.code == params.MISSING and "end" in caught.value.message + + +# ========================================================================== +# 只算选中的指标(K08 S2):只选 A 时 B 那条 SQL 不进图,也不要求它的参数 +# ========================================================================== + +#: buyer 只有 B 那条查询用:只选 A 时这次不必给 +FIELDS_AB = [{"name": "start", "required": True}, {"name": "end", "required": True}, + {"name": "buyer", "required": True}] +SQL_A = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' " + "AND paid_at >= '{{ input.start }}' AND paid_at < '{{ input.end }}'") +SQL_B = SQL_A + " AND region = '{{ input.buyer }}'" + + +def two_metric_graph(*, on_missing: bool = True) -> dict: + """一张卡两个指标、两条各自独立的查询(B 多要一个 buyer)。""" + card: dict = {"caliber": "双指标", "caliber_version": "v1", + "metrics": [{"id": "gmv", "name": "销售额", "expression": "cell(nodes.fetch_a, 0, 'gmv')"}, + {"id": "n", "name": "单量", "expression": "cell(nodes.fetch_b, 0, 'n')"}]} + if on_missing: + card["on_missing"] = "null" + return S.chain(S.node("start", "input", fields=FIELDS_AB), + S.node("fetch_a", "tool", tool=S.tool(), args={"sql": SQL_A}), + S.node("fetch_b", "tool", tool=S.tool(), args={"sql": SQL_B}), + S.node("card", "metrics", **card), + S.node("out", "output", fields=[{"name": "r", "value": "{{ nodes.card.text }}"}])) + + +def shared_graph() -> dict: + """两个指标读同一条取数(共享 SQL)。""" + return S.chain(S.node("start", "input", fields=FIELDS_AB[:2]), + S.node("fetch", "tool", tool=S.tool(), args={"sql": SQL_A}), + S.node("card", "metrics", caliber="共享取数", caliber_version="v1", + metrics=[{"id": "gmv", "name": "销售额", "expression": "cell(nodes.fetch, 0, 'gmv')"}, + {"id": "n", "name": "单量", "expression": "cell(nodes.fetch, 0, 'n')"}]), + S.node("out", "output")) + + +async def composed_graph(workflow_id: str, *, metrics: list[str] | None = None) -> tuple[dict, "compose.Composed"]: + """照 test_ledger_compose 的做法:把口径拷进问数据的图,交回 (图, 这次选用)。""" + async with SessionLocal() as session: + kind = await CaliberKind.load(session, compose=True) + made = compose.Composer(list(kind.options)).compose( + {"op": "use_caliber", "id": "c1", "workflow_id": workflow_id, "version": 1, "card": "card", + "metrics": metrics or ["gmv"], "inputs": {"start": "2026-09-01", "end": "2026-09-08"}}, taken=set()) + return S.chain(S.node("start", "input", fields=[{"name": "question"}]), *made.nodes, + S.node("write", "report", instructions="写周销售"), + S.node("out", "output", fields=[{"name": "报告", "value": "{{ nodes.write.text }}"}])), made + + +def rendered_a() -> str: + return SQL_A.replace("{{ input.start }}", "2026-09-01").replace("{{ input.end }}", "2026-09-08") + + +async def test_only_the_selected_metric_s_sql_is_executed(monkeypatch, executed): + """组合式问数只选 gmv:B 那条查询不进图,实际发给数据库的只有 A 这一条(B 的参数这次不用给)。""" + wf = await S.publish(graph=two_metric_graph()) + graph, made = await composed_graph(wf) + assert [n["id"] for n in graph["nodes"] if n["type"] == "tool"] == ["c1_fetch_a"] + assert made.result()["selection"]["metric_ids"] == ["gmv"] + S.script(monkeypatch, "本周销售额 [[m:gmv]]。") + run = await run_manager.start(graph=graph, input_payload={"question": "九月第一周卖了多少"}, origin_kind="chat") + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + assert executed == [rendered_a()] # 一条:B 的零条 + + +async def test_a_shared_query_still_runs_and_declares_the_metric_it_used_to_compute(monkeypatch, executed): + """A 和 B 共用一条 SQL:选 A 那条照样执行(一次),结果里如实声明它还在算 B。""" + wf = await S.publish(graph=shared_graph()) + graph, made = await composed_graph(wf, metrics=["gmv"]) + [query] = made.closure.queries + assert query.computes_unselected == ("n",) and made.closure.query_ids == (f"{wf}:fetch",) + S.script(monkeypatch, "本周销售额 [[m:gmv]]。") + run = await run_manager.start(graph=graph, input_payload={"question": "九月第一周卖了多少"}, origin_kind="chat") + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + assert executed == [rendered_a()] + + +async def test_the_probe_of_a_selection_carries_only_the_selected_query(executed): + """派生探针按同一份选择裁:入口表单收窄到这次用的(不必给 buyer),拷出来的只有 A 那条查询。""" + wf = await S.publish(graph=two_metric_graph()) + async with SessionLocal() as session: + pinned = await derive.load_pinned(session, wf, 1, "card", metric_ids=["gmv"]) + probe = derive.caliber_probe(pinned) + assert [n["id"] for n in probe.graph["nodes"]] == [derive.ENTRY_ID, "fetch_a", "card", derive.EXIT_ID] + assert probe.graph["nodes"][0]["data"]["config"]["fields"] == FIELDS_AB[:2] + run = await run_manager.start(graph=probe.graph, input_payload={"start": "2026-09-01", "end": "2026-09-08"}) + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + assert executed == [rendered_a()] diff --git a/backend/tests/test_tool_evidence.py b/backend/tests/test_tool_evidence.py index fef08339..77a7890a 100644 --- a/backend/tests/test_tool_evidence.py +++ b/backend/tests/test_tool_evidence.py @@ -191,7 +191,9 @@ async def test_tool_node_writes_tool_and_query_entries(engine_up, shop): assert tool_entry == {"kind": "tool", "node_id": "fetch", "exec": 1, "artifact": end.data["artifact"], "tool": TOOL} assert query_entry == {"kind": "query", "node_id": "fetch", "exec": 1, "artifact": payload["artifact"], "via": end.data["artifact"], "tool": TOOL, "source": "shop", - "columns": ["gmv", "gmv_prev", "orders"], "rows": 1, "truncated": False} + "columns": ["gmv", "gmv_prev", "orders"], "rows": 1, "truncated": False, + # 实际执行的执行身份(K10):逻辑查询是本节点,这一次按运行 + 节点 + 执行序号 + "query_id": "fetch", "execution_id": f"{row.id}:fetch#e1", "attempt": 1} assert await ledger(row.id) == [tool_entry, query_entry] snap = artifact_store.load(payload["artifact"]) assert snap["rows"] == [[600.5, 300.0, 3]] diff --git a/backend/tests/test_variables.py b/backend/tests/test_variables.py index cfea3959..0ab0b4c0 100644 --- a/backend/tests/test_variables.py +++ b/backend/tests/test_variables.py @@ -341,3 +341,83 @@ def test_auto_provided_variables_are_not_nagged_about() -> None: unused = [i.message for i in report.issues if "没有任何地方引用" in i.message] assert not any("item_index" in m for m in unused), unused assert not any("vars.items" in m for m in unused), unused + +# -------------------------------------------------------------------------- +# 已经渲染成字面值的参数(K01):args / sql 里的 {{ }} 是数据,不是变量引用 +# -------------------------------------------------------------------------- + + +def _literal(config: dict, node_id: str = "fetch", node_type: str = "tool") -> dict: + """给节点配一份参数契约(ledger/params 的 marker):args / sql 是服务端渲染好的字面值,契约与它绑定(rendered)。""" + from app.ledger import params + + key = params.LITERAL_KEY[node_type] + return {**config, params.KEY: params.marker(rendered=config.get(key), + source={"kind": "caliber", "node_id": node_id})} + + +def test_literal_parameters_are_not_read_as_variable_references() -> None: + """带参数契约的节点:args 里取不到同名变量的 {{ }} 是数据,不报「没有任何节点产出」。 + + 组合式问数拷进来的取数节点、对账图里服务端拼的对齐语句都是这种:值来自口径参数或查询结果,里面带 `{{ }}` 纯属巧合 + (用户写的就是这几个字)。报成模板引用会让整张图跑不起来——那是把数据当模板看。 + """ + g = _graph([ + {"id": "start", "type": "input", "config": {"fields": [{"name": "question"}]}}, + {"id": "fetch", "type": "tool", + "config": _literal({"tool": "db_query__shop", "assign_to": "rows", + "args": {"sql": "SELECT * FROM orders WHERE region = '{{ vars.region }}'"}})}, + {"id": "merge", "type": "merge", + "config": _literal({"inputs": {"o": "fetch"}, + "sql": "SELECT * FROM o WHERE 备注 = '{{ vars.region }}'"}, node_id="merge", + node_type="merge")}, + ], [("start", "fetch"), ("fetch", "merge")]) + assert [i for i in analyze(g).issues if i.level != "info"] == [] + + +def test_a_normal_template_node_is_still_checked() -> None: + """没有契约的节点照旧全扫:拼错、取不到的变量仍然要在跑之前说破。""" + g = _graph([ + {"id": "start", "type": "input", "config": {"fields": [{"name": "question"}]}}, + {"id": "fetch", "type": "tool", + "config": {"tool": "db_query__shop", "args": {"sql": "SELECT * FROM orders WHERE region = '{{ vars.region }}'"}}}, + ], [("start", "fetch")]) + errs = [i for i in analyze(g).issues if i.level == "error"] + assert len(errs) == 1 and "vars.region" in errs[0].message, [i.message for i in errs] + + +def test_literal_parameters_only_skip_their_own_key() -> None: + """契约只让 args / sql 那几个键不去当模板看:同一个节点别处的模板照旧扫。""" + g = _graph([ + {"id": "start", "type": "input", "config": {"fields": [{"name": "question"}]}}, + {"id": "fetch", "type": "tool", + "config": _literal({"tool": "db_query__shop", + "args": {"sql": "SELECT '{{ vars.region }}' AS r"}, + "note": "{{ vars.region }}"})}, + ], [("start", "fetch")]) + errs = [i for i in analyze(g).issues if i.level == "error"] + assert len(errs) == 1 and errs[0].field == "note", [i.model_dump() for i in errs] + + +def test_an_edited_node_loses_the_literal_exemption() -> None: + """契约与它注解的那条语句绑定:复制后改过 args / sql,契约作废,改过的内容照常当模板扫。 + + 复制一个服务端渲染好的取数节点、再改它的 SQL 是最常见的走法。旧契约留在节点上,如果不核对哈希就按 literal 跳过, + 一条改坏了的模板(引用没人产出的变量)会悄悄放行——运行前不再说破,运行时就渲染成空串。 + """ + from app.ledger import params + + original = _literal({"tool": "db_query__shop", "assign_to": "rows", + "args": {"sql": "SELECT '{{ vars.region }}' AS r"}}) + edited = {**original, "args": {"sql": "SELECT '{{ vars.region }}' AS r, {{ vars.quesiton }} AS q"}} + assert params.literal_keys(original, "tool") == ("args",) + # 改过之后契约不再成立 + assert params.literal_keys(edited, "tool") == () and params.marker_material(edited, "tool") is None + + g = _graph([ + {"id": "start", "type": "input", "config": {"fields": [{"name": "question"}]}}, + {"id": "copy", "type": "tool", "config": edited}, + ], [("start", "copy")]) + errs = [i for i in analyze(g).issues if i.level == "error"] + assert len(errs) == 2 and {i.path for i in errs} == {"vars.region", "vars.quesiton"}, \ + [i.message for i in errs] diff --git a/backend/tests/test_verify_agent.py b/backend/tests/test_verify_agent.py index 0a8c04d0..83be1584 100644 --- a/backend/tests/test_verify_agent.py +++ b/backend/tests/test_verify_agent.py @@ -792,3 +792,98 @@ async def test_a_failing_ledger_is_reported_not_raised(monkeypatch, shop): {"value": {"alias": "Q1", "row": 0, "column": "total"}, "verdict": "一致", "rationale": "x"}) out = await run(name) assert out.result is None and out.error + + +# -------------------------------------------------------------------------- +# K10:一次调用交回多条查询(口径查询)时的抽取、认工件与执行身份 +# -------------------------------------------------------------------------- + + +class _FakeQueryTool: + """交回一段固定内容的查询工具:`_run_tool` 按名字认身份、按结果摊条目,工具本身是什么不重要。""" + + name = "caliber_query" + + def __init__(self, payload: object) -> None: + self.payload = payload if isinstance(payload, str) else json.dumps(payload, ensure_ascii=False) + + async def ainvoke(self, args: dict) -> str: + return self.payload + + +async def _snapshot(run_id: str, *, column: str, node_id: str) -> str: + """一份查询快照工件,归属 run_id(内容寻址:列不同就是不同的工件)。""" + from app.data.catalog import QUERY_SNAPSHOT_KIND + + return await artifact_store.put_json({"columns": [column], "rows": [[1]], "sql": f"SELECT {column}"}, + kind=QUERY_SNAPSHOT_KIND, run_id=run_id, node_id=node_id) + + +async def test_a_multi_query_result_is_registered_item_by_item(): + """口径查询一次交回多条:逐条编号、逐条进核查自己的台账,执行身份照它自己带着的那一份。""" + run_id = uuid.uuid4().hex + first = await _snapshot(run_id, column="gmv", node_id="sales") + second = await _snapshot(run_id, column="peak", node_id="shared") + payload = {"tool": "caliber_query", "kind": "caliber_query", "ok": True, "run_id": "child-run", "queries": [ + {"artifact": first, "columns": ["gmv"], "row_count": 1, "truncated": False, "source": "shop", + "query_id": "wf:sales", "execution_id": "child-run:sales#e1", "attempt": 1}, + {"artifact": second, "columns": ["peak"], "row_count": 1, "truncated": False, "source": "shop", + "query_id": "wf:shared", "execution_id": "child-run:shared#e1", "attempt": 1}]} + queries: list[dict] = [] + ledger: list[dict] = [] + out = await verify_agent._run_tool(_FakeQueryTool(payload), "caliber_query", {}, "c1", None, None, + queries, ledger, "check", run_id=run_id) + assert out.startswith("【证据 Q1、Q2】"), "多条查询逐条编号(以前一条都认不出来)" + assert [q["alias"] for q in queries] == ["Q1", "Q2"] + assert [q["artifact"] for q in queries] == [first, second] + assert [e["artifact"] for e in ledger] == [first, second] and len(ledger) == 2, "两条都进台账" + # 执行身份照抄口径查询自己带着的那一份:逻辑查询、这一次执行、第几次 + assert [q["query_id"] for q in queries] == ["wf:sales", "wf:shared"] + assert [q["execution_id"] for q in queries] == ["child-run:sales#e1", "child-run:shared#e1"] + assert [q["attempt"] for q in queries] == [1, 1] + assert all(q["row_count"] == 1 and q["truncated"] is False and q["tool"] == "caliber_query" for q in queries) + # 交回结果里的样子不变:老消费方按这几个键读(outcome 的 shown、_Cells、_QUERY_KEYS) + assert all({"alias", "artifact", "sql", "row_count", "truncated", "source", "tool", "call_id"} <= set(q) + for q in queries) + + +async def test_a_forged_or_other_runs_query_does_not_enter_the_ledger(): + """名字对了工件也得对:伪造的、别的运行落的、不是查询快照的工件都不编号、不进台账。""" + run_id = uuid.uuid4().hex + real = await _snapshot(run_id, column="gmv", node_id="sales") + item = {"artifact": real, "columns": ["gmv"], "row_count": 1, "truncated": False, "source": "shop", + "query_id": "wf:sales", "execution_id": "child-run:sales#e1", "attempt": 1} + payload = {"tool": "caliber_query", "kind": "caliber_query", "ok": True, "run_id": "child-run", + "queries": [{**item, "artifact": "a" * 64}, item]} + queries: list[dict] = [] + ledger: list[dict] = [] + out = await verify_agent._run_tool(_FakeQueryTool(payload), "caliber_query", {}, "c1", None, None, + queries, ledger, "check", run_id=run_id) + assert out.startswith("【证据 Q1】") and [q["artifact"] for q in queries] == [real] + + # 同一份真工件,换一个运行 id:不是这次运行(也不是它派生的子运行)落的,整条都不认,原话交回模型 + text = json.dumps(payload, ensure_ascii=False) + other: list[dict] = [] + other_ledger: list[dict] = [] + out = await verify_agent._run_tool(_FakeQueryTool(text), "caliber_query", {}, "c1", None, None, + other, other_ledger, "check", run_id=uuid.uuid4().hex) + assert out == text and not other and not other_ledger, "别的运行落的查询快照一条都不记" + + +async def test_a_single_db_query_keeps_its_old_shape(): + """单条数据源查询照旧:一个 Qn、内容前面一行编号,台账条目与查询清单的键一个不少(另加执行身份)。""" + payload = {"artifact": "b" * 64, "columns": ["total"], "rows": [[1]], "truncated": False, "source": "shop", + "sql": "SELECT 1"} + text = json.dumps(payload) + queries: list[dict] = [] + ledger: list[dict] = [] + out = await verify_agent._run_tool(_FakeQueryTool(text), "db_query__shop", {"sql": "SELECT 1"}, "c1", None, None, + queries, ledger, "check", run_id="run-1") + assert out == f"【证据 Q1】\n{text}" + [query] = queries + assert query["alias"] == "Q1" and query["row_count"] == 1 and query["rows"] == [[1]] and query["sql"] == "SELECT 1" + [entry] = ledger + assert entry["kind"] == "query" and entry["artifact"] == "b" * 64 and entry["exec"] == 1 + assert entry["source"] == "shop" and entry["columns"] == ["total"] and entry["rows"] == 1 + # 执行身份按这次调用的 id 算(同 Agent 节点、调用工具节点);逻辑查询就是本节点 + assert entry["query_id"] == "check" and entry["execution_id"] == "run-1:check#c1" and entry["attempt"] == 1 diff --git a/frontend/src/api/caliberLedger.ts b/frontend/src/api/caliberLedger.ts index 8d60d0be..b24b1057 100644 --- a/frontend/src/api/caliberLedger.ts +++ b/frontend/src/api/caliberLedger.ts @@ -12,9 +12,10 @@ * 请求函数从 ./http 导入,不从 ./client 导入(client.ts 要导入这个文件,反过来就成了循环)。 */ import type { - CaliberDescriptor, CaliberDraft, CaliberDraftAttachOut, CaliberDraftSummary, CaliberTrialOut, CertifyQueue, DraftMetric, - DraftTrialOut, FreezeOut, LedgerFeedbackOut, LedgerFeedbackVerdict, LedgerIssueOut, LedgerReconcileIn, LedgerReconcileOut, - RunLedger, + CaliberDescriptor, CaliberDraft, CaliberDraftAttachOut, CaliberDraftSummary, CaliberTrialOut, CertifyQueue, DraftExpectIn, + DraftImportAcceptOut, DraftImportRun, DraftMetric, DraftOperation, DraftTrialOut, DraftValidationsOut, FreezeOut, + LedgerFeedbackOut, LedgerFeedbackVerdict, LedgerIssueOut, LedgerReconcileIn, LedgerReconcileOut, NlChangeOut, + NlChangePreviewOut, RunLedger, DraftValidationRecord, } from '../typesLedger' import { get, patch, post, type RequestOptions } from './http' @@ -62,10 +63,25 @@ export const caliberLedger = { draftTrial: (draftId: string, opts?: RequestOptions) => get(`${draftAt(draftId)}/trial`, opts), /** * 按填好的入口字段再试运行一次(POST 同一个路径):参数按入口字段校验,缺必填回 422; - * 返回 {run_id, status, metrics, error},status 是 running / succeeded / failed / needs_input + * 返回 {run_id, status, metrics, error},status 是 running / succeeded / failed / needs_input。 + * + * 带 expect(K05 的固定期望)时,期望里的指标必须是这张卡上的、要**逐条给全**(不合规回 422,不发起运行); + * 跑完把结果追加成一条验证记录。不带 expect 也能跑,但那样只记 observed——没有独立期望就不能算验证通过。 */ - runDraftTrial: (draftId: string, inputs: Record) => - post(`${draftAt(draftId)}/trial`, { inputs }), + runDraftTrial: (draftId: string, inputs: Record, expect?: DraftExpectIn) => + post(`${draftAt(draftId)}/trial`, expect ? { inputs, expect } : { inputs }), + /** 这份草稿的验证记录(新的在前)+ 总情况 + 字段基线状态:K06 读的那份契约 */ + draftValidations: (draftId: string, opts?: RequestOptions) => + get(`${draftAt(draftId)}/validations`, opts), + /** + * 对一条验证记录做一次审阅(builder 及以上):confirmed / rejected,只追加。请求体里**没有 actor**, + * 审批人取服务端身份(关登录时是自报署名);没有能记下来的主体时回 409 review_actor_required。 + * 返回里的 record 带这次决定和 covers_current(所审记录还算不算覆盖当前定义/绑定) + */ + reviewValidation: (draftId: string, recordId: string, body: { decision: 'confirmed' | 'rejected'; note?: string; + metrics?: string[] }) => + post<{ ok: boolean; draft_id: string; record: DraftValidationRecord }>( + `${draftAt(draftId)}/validations/${encodeURIComponent(recordId)}/review`, body), /** 选文档发起起草:documents 是要用的知识库文档 id,guidance 是给模型看的附加要求, * fixed_filters 是每次跑都不变的条件(工厂、产线、属性组),服务端要求写死在 SQL 里、不做成入口字段 */ extractDraft: (body: { documents: string[]; collection?: string; datasource_id?: string; guidance?: string; @@ -73,13 +89,85 @@ export const caliberLedger = { post<{ draft_id: string; status: string }>('/ledger/drafts/extract', body), /** * 改标题、整体换掉指标、或把答清的问题消掉(resolved 是问题原文)。服务端据此重算状态:还有问题 → questions_open, - * 否则 ready;已经接上或驳回的不改状态 + * 否则 ready;已经接上或驳回的不改状态。 + * + * 已接管的草稿(有取数图)是 K02 的并发保护对象:expected_revision 是读草稿时给的 revision(必带,缺了 409 + * revision_required),target.card_id 在多张可写的卡时必须给(否则 409 card_required),request_id 是幂等键—— + * 同一个键带着同样的内容重发不会多存一版。基准版本过期回 409 stale_revision(另带 current_version), + * 这时保留页面上的编辑、刷新详情后再改。 + * + * 走 operations 时回执里另带 change 一段(变更分类、影响指标、定义指纹前后值、失效说明、绑定状态);同键同内容的 + * 重放交回的是当前视图(带 replayed),不再重算一份回执 */ - patchDraft: (draftId: string, body: { title?: string; metrics?: DraftMetric[]; resolved?: string[] }) => - patch(draftAt(draftId), body), + patchDraft: (draftId: string, body: { + title?: string; metrics?: DraftMetric[]; resolved?: string[] + /** K03 的字段操作:按稳定 metric_id + 字段路径改一处;和 metrics / resolved 互斥(422 change_conflict) */ + operations?: DraftOperation[] + expected_revision?: number; request_id?: string + target?: { workflow_id?: string; card_id?: string } + }) => patch(draftAt(draftId), body), /** 接上一次真实运行补取数路径(app/ledger/docattach.py):由它建工作流和版本,定义来自草稿 */ attachDraft: (draftId: string, runId: string) => post(`${draftAt(draftId)}/attach`, { run_id: runId }), /** 「不是口径」:置 rejected,写一条审计,以后不再出现在列表的待办里 */ dismissDraft: (draftId: string, note?: string) => post<{ ok: boolean; draft_id: string; status: string }>(`${draftAt(draftId)}/dismiss`, { note: note ?? null }), + + // ---- K11 增量重导入(app/ledger/reimport.py、api/caliber_import.py;搭建者)---- + /** 这份草稿的导入记录(新的在前),每条都带工作项和逐字段三方 */ + imports: (draftId: string, opts?: RequestOptions) => + get<{ runs: DraftImportRun[] }>(`${draftAt(draftId)}/imports`, opts), + /** + * 按这份草稿的来源文档重新抽一次候选 R(后台跑)。**不改 L、不改 B**:真正落到图上的只有 accept。 + * 带 request_id 的:同一份草稿 + 同一个键已经建过就交回那一次,不重复抽、不重复建工作项 + */ + createImport: (draftId: string, requestId?: string) => + post(`${draftAt(draftId)}/imports`, requestId ? { request_id: requestId } : {}), + /** 一次导入的现状:工作项、逐字段三方、冲突;queued / running 时轮询它 */ + importRun: (runId: string, opts?: RequestOptions) => + get(`/ledger/imports/${encodeURIComponent(runId)}`, opts), + /** + * 按**现在的** L / B 重算这次导入还没决定的三方,并刷新每项的比较锚点(人处置过的决定不动)。 + * 这是 409 import_stale_l 之后的恢复动作:候选算出来之后 L 被人改过,不能只把 expected_revision 更新到最新一版 + * 就覆盖上去,要按现在的口径重新算、人重新看过再接受 + */ + refreshImport: (runId: string) => + post(`/ledger/imports/${encodeURIComponent(runId)}/refresh`, {}), + /** 人工把一条工作项对到图上某条指标(空串 = 取消对齐):baseline_unknown 和同名不同范围都走这里 */ + alignImportItem: (runId: string, itemId: string, metricId: string) => + post(`/ledger/imports/${encodeURIComponent(runId)}/items/${encodeURIComponent(itemId)}/align`, + { metric_id: metricId }), + /** + * 接受选定字段:**一次性**落到 L(新增一版图)并按被接受的那几格推进 B。要带读到的基准版本 + * (expected_revision,缺了 409 revision_required、对不上 409 stale_revision)和幂等键。 + * items 一律按**工作项身份**(item_id)指认:同一条指标上可能有多条工作项(重复的候选、同一位被两项候选各带一份 + * 说法),按 metric_id 指会指错(服务端只在旧调用只给 metric_id 时才要求它在这条导入里唯一对得上一条); + * fields 要**明确列出来**(页面列了几格就只接受几格,不靠 auto 猜)。服务端发现要接受的格子「当前内容和算候选时的 + * 那一版不一样」时回 409 import_stale_l(另带 fields 指出是哪几格),这时不能只更新 expected_revision 覆盖上去, + * 要先 refreshImport 按现在的口径重算三方再让人确认 + */ + acceptImport: (runId: string, body: { + items: { item_id: string; metric_id?: string; fields: string[] }[] + expected_revision?: number; request_id?: string + }) => post(`/ledger/imports/${encodeURIComponent(runId)}/accept`, body), + /** 拒绝选定字段:保持 L 不动,也不推进 B。同样按工作项身份(item_id)指认;老调用可以用 seq */ + rejectImport: (runId: string, body: { + items: { item_id: string; metric_id?: string; seq?: number; fields: string[] }[]; note?: string + }) => post(`/ledger/imports/${encodeURIComponent(runId)}/reject`, body), + /** 显式恢复:把这次导入重新排进后台,续做还没完成的工作项(已接受 / 拒绝的不动,不重复建版) */ + resumeImport: (runId: string) => + post(`/ledger/imports/${encodeURIComponent(runId)}/resume`, {}), + + // ---- K12 受限的自然语言修改(app/ledger/nlchange.py;搭建者)---- + /** 一句话 → 受限修改提案:**只读**,不落库、不新增版本;说不清就只回澄清项 */ + changeProposal: (draftId: string, body: { instruction: string; metrics?: string[] + target?: { workflow_id?: string; card_id?: string } }) => + post(`${draftAt(draftId)}/change-proposal`, body), + /** + * 一句话改口径:默认只预览(confirm=false);**confirm=true 才按同一批操作落一版**(内部翻成一次 + * DraftPatchIn 交给现有变更服务:expected_revision / request_id / CAS / 绑定同步一条不少)。 + * 说不清时回 409 并带澄清项,一条操作都不落 + */ + nlChange: (draftId: string, body: { instruction: string; confirm: boolean; expected_revision?: number + request_id?: string; metrics?: string[]; target?: { workflow_id?: string; card_id?: string } }) => + post(`${draftAt(draftId)}/nl-change`, body), } diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 3947004e..ab8549d9 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -257,7 +257,10 @@ export const api = { name: string; description?: string; graph?: GraphSpec; tags?: string[] origin?: { run_id: string; conversation_id?: string; turn_id?: string } }) => post('/workflows', body), - update: (id: string, body: Partial & { note?: string }) => + /** 改工作流:带 graph 就是保存一版。expected_revision 是读到的 Workflow.version(K02 的乐观锁):对不上回 + * 409 stale_revision(另带 current_version),这时页面保留自己的编辑、也不自动重放,人确认后再按最新一版 + * 显式重试(或载入最新版本) */ + update: (id: string, body: Partial & { note?: string; expected_revision?: number }) => patch(`/workflows/${id}`, body), remove: (id: string) => del(`/workflows/${id}`), duplicate: (id: string) => post(`/workflows/${id}/duplicate`), diff --git a/frontend/src/lib/terms.ts b/frontend/src/lib/terms.ts index cc153e90..aee9c8f0 100644 --- a/frontend/src/lib/terms.ts +++ b/frontend/src/lib/terms.ts @@ -963,6 +963,24 @@ export const SUBGRAPH_UPGRADE_HELP = '所固定的版本之后,被引用的工 export const upgradeNewerText = (latest: number, pinned: number) => `上游已有 v${latest}(固定的是 v${pinned}):发起正式运行前须在下方声明升版处置,否则正式运行将被拦截` +/** + * 保存被服务端按 stale_revision 拒了(K02):同一张图有人先改过。画布上的修改原样留着(还是「未保存」), + * 也不自动重发;页面上给两条明确的路让人自己选 + */ +export const STALE_SAVE_TEXT = { + banner: (base: number, current: number | null) => current == null + ? `这张图有人先改过(你基于 v${base}):画布上你的修改还在,没有替你重发` + : `这张图有人先改过(你基于 v${base},服务端现在是 v${current}):画布上你的修改还在,没有替你重发`, + rebase: '用最新版本再保存', + rebaseHint: '按服务端现在这一版为基准再存一版:画布上这份成为新的一版,别人刚改的那一版留在版本历史里', + reload: '载入最新版本', + reloadHint: '丢掉画布上还没保存的改动,换成服务端现在这一版', + reloadTitle: '载入最新版本?', + reloadBody: '画布上还没保存的修改会被丢掉,换成服务端上现在这一版。', + reloadConfirm: '载入最新版本', + dismiss: '先不改了', +} as const + /** * 发布前检查与自动修复:发布弹窗和问题面板的「发布前检查」共用一套说法。 * 原则写在话里:修复只出预览、人确认了才存草稿,永远不替人发布 diff --git a/frontend/src/lib/termsLedger.ts b/frontend/src/lib/termsLedger.ts index f04a1d79..79cff358 100644 --- a/frontend/src/lib/termsLedger.ts +++ b/frontend/src/lib/termsLedger.ts @@ -97,6 +97,13 @@ export const LEDGER_UI = { cancel: '取消', launched: '已发起对账,结果在下面', readOnly: '对话在回收站中,恢复后才能对账', + /** + * 这一项当前这个身份**发不了**(服务端没给这一项身份,只给了说明):不摆按钮,只写清是哪份口径、为什么。 + * 允许的理由只有授权这一条(应用授权里给到「使用」),不替服务端编别的原因。 + */ + unavailable: (caliber: string) => `对账:${caliber}(当前这个身份没有发起对账的授权)`, + unavailableHint: '要对这份口径对账,需要有它的使用授权;这里只写清差在哪,发不出请求', + notAvailable: '这一项没有可发起对账的授权(服务端没给身份):这里只写差在哪', }, /** 对账的结果卡片 */ result: { @@ -333,6 +340,8 @@ export const LEDGER_UI = { noMetrics: '没有整理出指标', noMetricsBody: '文档里没有能逐字核对上引用的指标定义,可以换一份文档或补充起草要求后重来', synonyms: (list: string) => `又称:${list}`, + /** 指标业务写法那一行:标签 + 说法 */ + businessValue: (value: string) => `:${value}`, unit: '单位', decimals: '小数位', expression: '表达式', @@ -356,6 +365,13 @@ export const LEDGER_UI = { resolveHint: '在业务上问清之后勾选对应的问题,移除后状态会跟着变', resolveNeed: '请先勾选已经问清的问题', resolved: (n: number) => `已移除 ${formatNumber(n)} 个问题`, + /** 图上有多张可写的口径卡、又认不出唯一目标:要人去画布上确认改哪一张(K02) */ + cardAmbiguous: '这份草稿的图上有好几张可写的口径卡:请先到画布上确认要改哪一张', + cardMissing: '这份草稿的图上看不到可写的口径卡:请到画布上核对这张图', + /** 写入被拒(有人先改过):勾选还在、也不会自动重发,人确认后再点一次(K02) */ + writeStale: (current: number | null, base: number | null) => current == null + ? `这条口径已经被别处改过(你基于 v${base ?? '?'}):勾选的问题还在,确认后再点一次` + : `这条口径已经被别处改过(你基于 v${base ?? '?'},服务端现在是 v${current}):勾选的问题还在,确认后再点一次`, dropped: '被丢弃的条目', droppedHint: '带不了能对照数据目录的取数,或引用无法逐字核对上的指标不留下', uncovered: (n: number) => `还没起草出来的指标(${formatNumber(n)} 条)`, @@ -409,6 +425,343 @@ export const LEDGER_UI = { dismissed: '已驳回,这份草稿不再出现在待办里', }, + // ---- 工作台:业务规则(K04 的能力描述 + K06 的改法;只在服务端说得出能改什么时才开表单)---- + rules: { + title: '业务规则', + hint: '这两项是业务定义的写法。保存时服务端在同一个版本里把取数一起改过来;改不了的原样保留,并写清原因', + fieldHelp: (help: string) => help, + /** 这一项现在取值不一致(同一张卡上的指标写法不同):不替人选一个默认值 */ + mixed: '现在写法不一致', + mixedHint: '保存后这些指标会统一成选中的写法', + keep: '保持各自现在的写法', + /** 这一项这张卡上没人声明:改不了(没有落点的取数不会被硬改) */ + fieldNone: '这张卡上的指标没有声明这一项', + /** 保存后会变哪几条指标:指标名 + 这一项现在 → 保存后 */ + previewTitle: '保存后会变成', + before: '现在', + after: '保存后', + unaffected: (n: number) => `另有 ${formatNumber(n)} 条指标没有声明这一项,这次不动它们`, + unaffectedHint: '要改它们得先由技术侧在指标上声明这两项、并给取数加上受控绑定', + affected: (n: number) => `会改到 ${formatNumber(n)} 条指标`, + noChange: '还没有改动:选一个和现在不一样的写法,这里就会列出会改到哪些指标', + save: '保存这次修改', + saving: '正在保存…', + saveNeedChange: '先选一个和现在不一样的写法', + /** 保存回执 */ + saved: (version: number | null) => version == null ? '已保存' : `已保存成 v${formatNumber(version)}`, + savedAligned: '定义和取数已经在同一个版本里改过来了', + savedNotSynced: '定义已经存下来了,取数一个字没动', + savedNoChange: '这次操作没有改动任何内容:图没有换版本', + invalidated: '这张卡的内容变了:旧的试运行和验证不再算覆盖这一版,请重新试运行', + nextStep: '下一步:按新定义重新试运行,并对一次独立样例', + replayed: '这一次和上一次是同一个请求,服务端认得出来,没有多存一版', + /** 基准版本过期:保留页面上的选择,不自动重发 */ + stale: (current: number | null, base: number | null) => current == null + ? `这条口径已经被别处改过(你基于 v${base ?? '?'}):你选好的写法还在,确认后再点一次「保存这次修改」` + : `这条口径已经被别处改过(你基于 v${base ?? '?'},服务端现在是 v${current}):你选好的写法还在,确认后再点一次`, + /** 撤销:用保存前的值构造逆操作,再存一版,不顺着一版整份覆盖 */ + undo: (n: number) => `撤销这次修改(回到 ${formatNumber(n)} 处改动之前的值)`, + undoing: '正在撤销…', + undone: (version: number | null) => version == null ? '已撤销这次修改' : `已撤销这次修改,现在这一版是 v${formatNumber(version)}`, + undoHint: '撤销也是新增一版(按当前版本和新的请求键提交逆操作),不改写已经存下的历史版本', + /** 不能改的资产:照实说为什么,并给技术待办 */ + readOnly: '这份草稿现在不能在这里改', + unbound: '这张卡上的指标没有声明统计时间口径和退款处理:按旧资产处理,不提供修改', + noCard: '图上看不到能改的口径卡:先在画布上确认要改哪一张', + noRevision: '这份草稿还没有版本号:刷新页面后再改', + noWorkflow: '这份草稿还没有取数图:起草完成或接上一次运行之后才能改业务规则', + /** 绑定的同步状态(同步只说这两边对得上,不等于验证通过) */ + status: { + aligned: '定义和取数已经同步', + needs_update: '定义和取数还没同步', + unsupported: '这条取数同步不了', + unbound: '这张卡没有声明业务字段', + } as Record, + alignedNote: '同步只说业务定义和这张取数对得上,不等于业务验证通过', + reason: '这条为什么改不了', + fixLabel: '技术待办', + fix: { + none: '不用处理', + sync: '可以按受控模板确定性同步:保存时会把取数一起改过来', + author: '要作者侧补或改受控绑定:这条取数里没有这个业务字段的落点,或者映射里没有这个取值', + manual: '先由人拿主意:同一条取数上的指标说法不一致,或者取数被手工改过', + } as Record, + fixNote: '这一条不受工作台影响,复杂或改不了的取数不会被字符串替换硬改', + }, + + // ---- 工作台:验证与审阅(K05 的记录,K06 的读法)---- + validation: { + title: '验证与审阅', + records: '验证记录', + empty: '还没有验证记录', + emptyBody: '按入口字段试运行一次就会留下一条记录;带独立期望时才能判「对得上」', + counts: (total: number, covering: number) => + `${formatNumber(total)} 条记录 · 覆盖当前版本 ${formatNumber(covering)} 条`, + method: (version: number) => `比较方法 v${formatNumber(version)}`, + /** 结论:只有「有独立期望对得上」并且「有覆盖它的认证审阅」才是验证通过 */ + verdict: { + none: '还没有验证记录', + stale: '现有记录不覆盖这一版', + observed: '只记了试运行结果', + mismatched: '和独立期望对不上', + failed: '试运行没有成功', + unverified: '还不能算验证通过', + verified: '验证通过', + rejected: '被审阅驳回', + } as Record, + /** 一条记录的状态 */ + status: { + matched: '和独立期望对得上', + mismatched: '和独立期望对不上', + observed: '只记了试运行结果', + unverified: '证据不足', + failed: '试运行没有成功', + } as Record, + covers: '覆盖当前版本', + notCovers: '不覆盖当前版本', + /** 只有服务端明确说覆盖才算覆盖:判不了就照实说判不了,不默认成覆盖 */ + coversUnknown: '覆盖判断未知', + coversHint: '定义、取数或绑定改过之后,旧记录留着可追,但不算覆盖这一版', + /** 结论依据的是哪一条记录:说出来,别让人把别的记录当成这一条的结论 */ + basis: (when: string, status: string) => `结论按 ${when} 那条记录(${status})`, + basisNone: '还没有一条记录可以下结论', + semanticGaps: (n: number) => `其中 ${formatNumber(n)} 条指标的语义说明仍待人工确认`, + expected: '独立期望', + expectedNone: '这条没有独立期望:只记试运行结果,不能算验证通过', + expectedSource: '期望来自', + sources: { + human_confirmed: '人工确认', + fixture: '固定夹具', + independent_computation: '独立计算', + } as Record, + expectedHint: '期望要独立于这次试运行:人工确认、固定夹具或独立算出来的标准答案,不能抄这次的结果当答案', + actual: '实际结果', + ok: '对得上', + notOk: '对不上', + unknown: '判不了', + noValue: '没有取到值', + rowsHint: (rows: number | null) => rows == null ? '' : `${formatNumber(rows)} 行`, + masked: '已遮罩', + problems: '这一条记下的问题', + review: '审阅', + noReview: '还没有审阅决定', + reviewConfirmed: '确认', + reviewRejected: '驳回', + reviewBy: (who: string, verified: boolean) => verified ? `由 ${who}` : `由 ${who}(自报署名,未认证)`, + reviewScope: '确认范围', + /** 确认范围没有盖住这条记录的全部指标:不能当成整卡通过 */ + reviewPartial: '没有盖住这条记录的全部指标:不能当整卡通过', + reviewCovers: '这次审阅覆盖当前版本', + reviewNotCovering: '这条不覆盖当前版本:确认了也不算覆盖这一版', + reviewCoversUnknown: '这次审阅的覆盖判断未知', + reviewNote: '说明(可空)', + reviewNotePlaceholder: '例如:对过业务口径和样例来源', + confirm: '确认这条', + reject: '驳回这条', + reviewing: '正在提交审阅…', + reviewDone: (decision: string) => `已记录一次审阅:${decision}`, + reviewScopeHint: '审阅只认服务端身份,界面代写不了审批人;同一份记录可以再审,显示的是最新一条', + baseline: '导入基线', + baselineKnown: (revision: number | null, metrics: number, fields: number) => + `有可还原的导入基线${revision != null ? `(第 ${formatNumber(revision)} 版接受)` : ''}:` + + `${formatNumber(metrics)} 条指标、${formatNumber(fields)} 个字段`, + baselineUnknown: '这份草稿没有导入基线:当时被接受的导入值还原不出来,不能拿现在的内容当作它', + baselineHint: '基线说的是「上次被接受的导入值」,人工改过这里的内容不会推进它', + /** 确认范围没盖住整条记录时的说明:服务端按范围收回也好、页面自己按范围收回也好,都用同一句 */ + partialVerdict: (covered: string, missed: string, total: number) => + `这次确认盖住了 ${covered || '—'},没有盖住 ${missed}(这条记录一共 ${formatNumber(total)} 条指标):` + + '不能算整卡验证通过', + /** 试运行那一块里的「这次试运行的验证记录」:只说本次那一条,旧记录不冒充本次 */ + trialRecord: '这次试运行的验证记录', + trialWaiting: '试运行还在进行,正在等本次的验证记录', + trialNoRecord: '这次试运行还没有留下验证记录:缺证据不能算验证通过', + /** 试运行那一条的紧凑写法:旁边就是状态和覆盖判断,不铺开整句 */ + noExpectation: '没有独立期望', + /** 带独立期望试运行 */ + trialWithExpect: '带独立期望试运行', + trialWithExpectHint: '先改上面那两项业务规则、或确认现在的写法就是要验的,再填标准答案试一次', + expectFor: (name: string) => `${name} 的期望值`, + expectNeedAll: '要逐条给全卡指标,不能只给其中几条', + expectSourceLabel: '期望来自', + expectSubmit: '带期望试运行', + expectSubmitting: '正在发起…', + runTrial: '不带期望试运行', + openRun: '看这次运行', + more: (n: number) => `展开其余 ${formatNumber(n)} 条记录`, + fieldsHint: '这里只摆指标值和验证依据,不显示取数语句、内部编号和字段路径', + }, + + // ---- K11 增量重导入:B / L / R 三方、按字段接受 / 拒绝、人工对齐、显式恢复 ---- + imports: { + title: '文档更新(重新读一遍文档)', + hint: '用最新的文档重抽一遍候选,和现在的内容、上次被接受的导入值逐字段比。' + + '候选只是候选:你不点接受,图上和字段基线一个字节都不动', + create: '按文档重新读一遍', + creating: '正在重新读取…', + started: '已开始重新读取:抽完候选会出现在下面', + createHint: '在服务端重读这份草稿的来源文档、抽候选,再逐字段比对;不改现在的内容', + runs: '重导入记录', + runsEmpty: '还没有重导入记录', + /** 一条记录:什么时候读的、已经处置了几条 */ + runLabel: (when: string, decided: number, total: number) => + `${when} · 已处置 ${formatNumber(decided)}/${formatNumber(total)} 条`, + open: '看这一次', + createdAt: (when: string) => `读过一次:${when}`, + itemsTotal: (n: number) => `这次抽出 ${formatNumber(n)} 条候选`, + /** run 的状态 */ + status: { + queued: '排队中', + running: '正在重新读取', + succeeded: '读完了', + partial: '读完了(有没抽全的)', + failed: '没有读完', + interrupted: '中断了,可以恢复', + cancelled: '已停止', + } as Record, + /** 逐格的三方状态说法 */ + state: { + update: '无冲突更新', + conflict: '人工修改冲突', + new: '新增候选', + missing: '这次没提取到', + manual: '需要人工对齐', + unchanged: '不变', + } as Record, + stateHint: { + update: '上次接受之后没人动过这一格:接受就取文档里的新说法', + conflict: '你人工改过这一格,文档又给了一个新说法:接受取文档的,拒绝就留你现在的内容', + new: '现在的内容和基线都没有这一格:文档新提出来的,可以接受', + missing: '这次没提取到这一格(漏提取不当删除):现在的内容原样留着,不能接受', + manual: '这一格没有可比的基线:要你人工对齐之后才能定', + unchanged: '和现在的内容或者基线一致:不用接受', + } as Record, + b: '上次被接受的导入值', + l: '现在的内容', + r: '这次文档里的说法', + noCell: '没有这一格', + /** 一格的值转成一行字:空值、空数组和结构化内容各有各的说法,不把 JSON 摆上来 */ + noValue: '没写', + emptyValue: '(空)', + objectValue: '(一段结构化内容)', + citationCount: (n: number) => `${formatNumber(n)} 段引用原文`, + /** 认不出的字段路径不摆原始路径,用一句笼统的说法 */ + otherField: '这一格', + /** 工作项的状态(逐字段算出来的那条) */ + itemStatus: { + pending: '还没处置', + accepted: '已接受', + rejected: '已拒绝', + partial: '有漏提取的格子', + failed: '这条没抽好', + } as Record, + accept: '接受', + reject: '拒绝', + /** 拒绝的说明(可空):记在这一次的决定上 */ + notePlaceholder: '拒绝的说明(可空)', + acceptSelected: (n: number) => `接受选中的 ${formatNumber(n)} 格`, + rejectSelected: (n: number) => `拒绝选中的 ${formatNumber(n)} 格`, + accepting: '正在接受…', + rejecting: '正在拒绝…', + /** 一条上所有「无冲突更新 + 新增候选」一次收掉;也是一次显式的点击 */ + acceptClean: (n: number) => `接受这条上无冲突的 ${formatNumber(n)} 格`, + nothingSelected: '先选要接受或者拒绝的格子', + nothingClean: '这条上没有可以直接接受的格子', + needRevision: '这份草稿还没有版本号:刷新页面之后再改', + missingNoDelete: '漏提取不当删除', + /** 人工对齐:没对上、或者同名不同范围时必须由人指定 */ + align: '对齐到哪条指标', + alignAction: '对齐', + aligning: '正在对齐…', + alignHint: '名字像不像不参与对齐,只认稳定身份和来源证据;机器对不上就必须由人指定', + alignNone: '不对齐(当作新指标)', + alignNeed: '先选要对齐到哪条指标', + reasonLabel: '为什么这么对', + reason: { + metric_id: '候选带着和图上一致的稳定身份', + evidence: '按来源证据对上了(引的是同一段原文)', + new: '没有对得上的指标:名字相不相似不参与自动合并', + manual: '要你来定:稳定身份对不上来源证据,或者证据对上了不止一条', + } as Record, + /** 显式恢复中断的那一次 */ + resume: '恢复这次导入', + resuming: '正在恢复…', + resumed: '已排进后台,正在接着读', + resumeHint: '续做还没完成的工作项;已经接受或者拒绝的不动,不会重复建版', + unfinished: (n: number) => `还有 ${formatNumber(n)} 条没做完`, + /** 基准版本过期:选择保留,不自动重发 */ + stale: (current: number | null, base: number | null) => current == null + ? `这条口径已经被别处改过(你基于 v${base ?? '?'}):你选好的格子还在,刷新后再点一次接受` + : `这条口径已经被别处改过(你基于 v${base ?? '?'},服务端现在是 v${current}):你选好的格子还在,刷新后再点一次接受`, + /** 服务端说这次导入比对的 L 已经过期(打开之后图被别处改过):按现在的 L / B 重算三方,不能拿旧 L 直接覆盖 */ + staleL: (names: string) => names + ? `这几格的当前内容和这次导入算候选时的那一版不一样了:${names}。` + + '已经按现在的口径把这次导入的三方重算了一遍,选好的格子还在,核对之后再点一次接受' + : '这次导入比对的还是旧的内容(你打开之后这张卡被别处改过):已经按现在的口径把这次导入的三方重算了一遍,' + + '选好的格子还在,核对之后再点一次接受', + accepted: (revision: number | null) => revision == null ? '已接受选中的格子' : `已接受选中的格子,落到 v${formatNumber(revision)}`, + acceptedHint: '这次图和字段基线是在同一次提交里推进的:没有接受的格子不会推进基线', + rejected: '已拒绝选中的格子:现在的内容和字段基线都没动', + replayed: '这一次和上一次是同一个请求,服务端认得出来:没有多存一版,基线也读得回来', + /** 字段基线覆盖到哪一步:有基线不等于整张都有 */ + coverageLabel: '字段基线的覆盖', + coverageComplete: '这张卡的每一格都有基线', + coveragePartial: (fields: number, metrics: number) => + `还没盖满这张卡:还有 ${formatNumber(fields)} 格没有基线` + + (metrics > 0 ? `、${formatNumber(metrics)} 条指标整条没有基线` : '') + + '。只有被接受的格子才往前走,没覆盖到的格子下次会按「新增候选 / 需要人工对齐」处理', + coverageUnknown: '这一份基线读不出来(不在、或者内容与哈希不符):不能拿现在的内容当作它', + coverageHint: '基线说的是「上次被接受的导入值」,人工改过现在的内容不会推进它', + conflicts: (n: number) => `这次有 ${formatNumber(n)} 格要人处置(冲突、要人工对齐、漏提取)`, + noItems: '这次没有抽出候选:可以再读一次,或者换一份文档重起草稿', + /** 没接管到图上:导入落不到图上 */ + readOnly: '这份草稿还没有取数图:重新导入落不到图上,先起草完成或者接上一次运行', + itemUnaligned: '这条还没对上图上的指标', + /** 一条指标在页面上找不到名字:不摆内部编号 */ + unknownMetric: '(这条指标在页面上找不到名字)', + fieldCount: (n: number) => `${formatNumber(n)} 格`, + }, + + // ---- K12 受限的自然语言修改:只产出提案,确认后才落一版 ---- + nl: { + title: '用一句话改口径', + hint: '只认已经声明过的业务写法(统计时间口径、退款处理这类)。先看会影响什么,确认之后才落一版;' + + '预览本身不写任何东西', + placeholder: '例如:订单金额按支付时间算,排除全额退款', + preview: '预览影响', + previewing: '正在看影响…', + needText: '先写一句要改什么', + /** 认可的操作:一条一行「指标 · 字段:现在 → 保存后」 */ + changeCount: (n: number) => `这句话会改到 ${formatNumber(n)} 处`, + noChange: '这句话没有能按字段改的地方', + now: '现在', + after: '保存后', + removeValue: '删掉这一项', + noValue: '没写', + /** 含糊的条件先澄清:一条操作都不产出 */ + clarifyTitle: '这句还说不清', + clarifyHint: '没有产出任何修改:说清之后再预览一次', + clarifyNoMatch: '这句话里没有能按字段改的已声明写法', + confirm: '确认并应用', + confirming: '正在应用…', + confirmHint: '确认之后才按这批操作落一版(带读到的版本和请求键);预览不会写任何东西', + needConfirm: '先预览,看清影响之后再确认', + /** 预览的是哪一段原文:确认发的就是这一段,页面显示的(A)和实际落下的(B)不是两句话 */ + previewedAs: (text: string) => `这份影响是按这一段原文算的:「${text}」`, + changedNotice: '输入改过了:上面还是上一次预览的结果,请重新预览之后再确认', + needPreviewAgain: '这句话改过了:要先重新预览;确认的必须是预览里那一段原文', + /** 服务端这次落下的操作和预览里的不是同一批:照实提示,让人到画布上核对 */ + mismatch: '服务端这次落下的操作和预览里的不是同一批:请到画布上核对这一版', + applied: (revision: number | null) => revision == null ? '已应用这句话' : `已应用这句话,落到 v${formatNumber(revision)}`, + invalidated: '这张卡的内容变了:旧的试运行和验证不再覆盖这一版,请重新试运行', + failed: '这次没有改任何东西:', + replayed: '这一次和上一次是同一个请求:没有多存一版', + readOnly: '这份草稿还没有取数图:一句话改不了任何东西,先起草完成或者接上一次运行', + noRevision: '这份草稿还没有版本号:刷新页面之后再改', + /** 一句话点到一条页面上找不到的指标:不硬套,也不摆内部编号 */ + unknownMetric: '(这条指标在页面上找不到名字)', + offerMissing: '这条指标在这张卡上找不到,没有落成修改', + }, + // ---- 设置:口径账本一组 ---- settings: { title: '口径账本', diff --git a/frontend/src/pages/StudioPage.tsx b/frontend/src/pages/StudioPage.tsx index 948275af..d3ac0da7 100644 --- a/frontend/src/pages/StudioPage.tsx +++ b/frontend/src/pages/StudioPage.tsx @@ -5,7 +5,7 @@ import { Redo2, RotateCw, Save, ShieldCheck, Square, Undo2, Variable, Wand2, XCircle, } from 'lucide-react' import clsx from 'clsx' -import { api } from '../api/client' +import { api, ApiError } from '../api/client' import { FlowCanvas } from '../canvas/FlowCanvas' import { Palette, PALETTE_SEARCH_ID } from '../canvas/Palette' import { InspectorSheet, revealField } from '../canvas/InspectorSheet' @@ -24,12 +24,12 @@ import { topology } from '../run/derive' import { EDIT_LOCK_TEXT, editLockOf, toGraph, useEditLock, useStudio } from '../store/studio' import { useCatalog, useOnReconnect } from '../store/catalog' import { - EmptyState, ErrorState, IconButton, Spinner, isComposing, promptDialog, toast, + EmptyState, ErrorState, IconButton, Spinner, confirmDialog, isComposing, promptDialog, toast, } from '../components/ui' import { isNetworkError } from '../lib/errors' import { formatClock } from '../lib/format' import { formatShortcut, isTypingTarget, matchShortcut } from '../lib/keys' -import { VERSION_LABEL_TEXT, WORKFLOW_STATUS_LABEL, publishedLevelOf } from '../lib/terms' +import { STALE_SAVE_TEXT, VERSION_LABEL_TEXT, WORKFLOW_STATUS_LABEL, publishedLevelOf } from '../lib/terms' import type { Workflow } from '../types' // 三栏的收起状态存在这台浏览器里。读写都可能抛(隐私模式、存储被禁),抛了就用默认值 @@ -124,6 +124,9 @@ export function StudioPage() { const redo = useStudio((s) => s.redo) const attachRun = useStudio((s) => s.attachRun) const analyzeNow = useStudio((s) => s.analyzeNow) + /** 保存被拒(stale_revision)时记下的两版:横幅按它写「你基于哪一版、服务端现在是哪一版」 */ + const staleSave = useStudio((s) => s.staleSave) + const clearStaleSave = useStudio((s) => s.clearStaleSave) /** 正在按 id 去取哪张图。防止 effect 重入时重复发请求、重复弹提示 */ const resolving = useRef(null) @@ -339,21 +342,52 @@ export function StudioPage() { if (selectedId && selectedId !== prev && !assistantRef.current) toggleAssistant(true) }, [selectedId, toggleAssistant]) - const doSave = useCallback(async (note?: string) => { + const doSave = useCallback(async (note?: string, opts?: { expectedRevision?: number }) => { const s = useStudio.getState() if (!s.workflow || s.copilot.active) return setSaving(true) try { - await save(note) + await save(note, opts) toast.ok(note ?? s.pendingNote ? `已保存:${note ?? s.pendingNote}` : '已保存') void refresh() } catch (e) { - toast.error(e) + // 冲突由画布上的横幅说清(两条路也在那里),不再叠一条同样的 toast——它正好落在横幅上,两条消息会盖住彼此 + if (!(e instanceof ApiError && e.status === 409 && e.code === 'stale_revision')) toast.error(e) } finally { setSaving(false) } }, [save, refresh]) + /** + * 冲突横幅上的「用最新版本再保存」:以服务端现在那一版为基准再存一次。这是人明确点的一次保存(横幅也是这么写的), + * 不是自动重放——没人点,画布上的修改就一直留着、不会自己发出去 + */ + const saveOnLatest = useCallback(async () => { + const s = useStudio.getState() + if (!s.workflow) return + const base = s.staleSave?.current ?? (await api.workflows.get(s.workflow.id)).version + await doSave(undefined, { expectedRevision: base }) + }, [doSave]) + + /** 冲突横幅上的「载入最新版本」:丢掉画布上的改动,换成服务端现在这一版。先问一句,不静默丢弃 */ + const reloadLatest = useCallback(async () => { + const s = useStudio.getState() + if (!s.workflow) return + const ok = await confirmDialog({ + title: STALE_SAVE_TEXT.reloadTitle, body: STALE_SAVE_TEXT.reloadBody, + consequences: ['画布上还没保存的修改会丢失', '载入之后可以照最新一版重新改'], + confirmLabel: STALE_SAVE_TEXT.reloadConfirm, danger: true, + }) + if (!ok) return + try { + const fresh = await api.workflows.get(s.workflow.id) + useStudio.getState().load(fresh) + toast.info(`已载入服务端现在这一版(v${fresh.version})`) + } catch (e) { + toast.error(e) + } + }, []) + const saveWithNote = useCallback(async () => { const note = await promptDialog({ title: '保存并写版本说明', @@ -627,6 +661,27 @@ export function StudioPage() { {/* 停靠栏做成挤压式而不是浮层:React Flow 的 Controls 和 MiniMap 是绝对定位在画布容器里的,浮层会把它俩埋掉,挤压会把它俩顶上去 */}
+ {staleSave && ( + /* 保存被拒(有人先改过同一张图):画布上的修改原样留着,也不自动重发;这里给两条明确的路 */ +
+ + + {STALE_SAVE_TEXT.banner(staleSave.base, staleSave.current)} + + + + +
+ )}
{loadError && loadError.id === workflowId && !workflow ? resolve(loadError.id)} className="h-full" /> diff --git a/frontend/src/pages/ledger/CaliberDrafts.tsx b/frontend/src/pages/ledger/CaliberDrafts.tsx index 38a6cc60..3d92d592 100644 --- a/frontend/src/pages/ledger/CaliberDrafts.tsx +++ b/frontend/src/pages/ledger/CaliberDrafts.tsx @@ -11,25 +11,61 @@ * (第 N 段),逐条的未决问题可以勾掉;被丢弃的条目单独列出原因;入口字段列出名字、类型、必填和缺省值; * - 发布:主按钮去画布审改并发布。「接上一次运行」只是辅助入口:已经有答案时让它认这份定义。 * + * 业务规则(K06 的工作台):服务端的能力描述(binding)说得出这张卡能按字段改哪几项业务写法(统计时间口径、 + * 退款处理)时,这里开出下拉;改完先把「哪几条指标、现在什么写法 → 保存后什么写法」列出来,再**一次**提交所有受 + * 影响指标的字段操作(PATCH 的 operations,带基准版本和请求键)。保存回执说清换成哪一版、绑定同步到哪一步、 + * 旧验证怎么失效,并按保存前的值给出「撤销这次修改」(逆操作 + 新请求键,再存一版,不整份覆盖)。写不进去 + * (基准版本过期)时保留这里的写法选择,刷新详情后由人显式再点一次;复杂或同步不了的照实写原因和技术待办。 + * 能力描述为空、认不出唯一的口径卡、没有版本号的资产保持只读。业务规则、变更预览和验证这几块只写业务说法, + * 不出现取数 SQL、节点 id 和字段路径。 + * + * 文档更新(K11 的增量重导入):新一段材料重抽成候选 R,和现在图上人工维护的 L、上次被接受的导入值 B 逐字段比。 + * **R 只是候选,不改 L、不改 B**:落到图上只有「接受选定字段」这一次显式动作(一次提交里新增一版图 + 按被接受的那几格 + * 推进 B)。逐格写清 B / L / R 和状态:无冲突更新、人工修改冲突、新增候选、需要人工对齐(没有可比基线时必须人工 + * 对齐到某条指标)、**漏提取**(不当删除,L 上的原值原样留着,也不能接受)。没接受过的格子不推进 B,所以这块另写 + * 清字段基线覆盖到哪一步(有基线不等于整张都有:partial 要明确说出来)。被中断的导入由人点「恢复」显式续跑, + * 已接受 / 拒绝的不重复动。基准版本过期时保留选好的格子,刷新后由人再点一次。 + * + * 用一句话改口径(K12):一句话只产出一份**只读提案**(K03 同一形状的 operations + 影响摘要 + 澄清项),页面上 + * 只写「哪条指标、哪一项写法、现在什么 → 保存后什么」,不摆 JSON、节点编号和字段路径。含糊的业务条件先显示澄清项、 + * 一条操作都不产出;确认(confirm=true)之后才按同一批操作落一版,失败时页面上什么都不改。 + * + * 验证与审阅(K05 的读法):这份草稿的验证记录(状态、独立期望、实际值、覆盖判断、审阅决定)和总情况一句 + * 「结论」分开写——试运行成功、绑定对齐、样例对得上都不等于验证通过;没有独立期望就照实说只记了试运行结果。 + * 审阅只有调真实接口这一条路(审批人取服务端身份),结果照服务端交回的说。 + * * 页面不显示执行值:取数 SQL 只作为模板只读展示,具体取数到画布上看。服务端把细状态折成四种阶段(起草中 / 待审 / * 已丢弃 / 失败),页面按阶段筛、按阶段画;细状态放在标签的悬停提示里。 */ import { useCallback, useEffect, useMemo, useRef, useState } from 'react' import { Link } from 'react-router-dom' -import { AlertTriangle, Check, ChevronLeft, FileText, PenLine, Play, RefreshCw, ScrollText } from 'lucide-react' +import { + AlertTriangle, Check, ChevronLeft, FileSearch, FileText, PenLine, Play, RefreshCw, RotateCw, ScrollText, Sparkles, Undo2, X, +} from 'lucide-react' import clsx from 'clsx' -import { api } from '../../api/client' +import { api, ApiError } from '../../api/client' import { EmptyState, ErrorState, Notice, PageHeader, Skeleton, Spinner, promptDialog, toast } from '../../components/ui' import { formatDateTime, formatTime } from '../../lib/format' import { LEDGER_UI } from '../../lib/termsLedger' +import { useAtLeast } from '../../store/auth' import { TrialResult, TrialValidation } from './TrialResult' import type { DataSourceName, KbDocument, Run } from '../../types' import type { - CaliberDraft, CaliberDraftStage, CaliberDraftStatus, CaliberDraftSummary, DraftAlignment, DraftCitation, DraftEntryField, - DraftMetric, DraftTrialMetric, DraftTrialOut, + CaliberDraft, CaliberDraftStage, CaliberDraftStatus, CaliberDraftSummary, DraftAlignment, DraftBinding, DraftChangeReceipt, + DraftCitation, DraftEditableField, DraftEntryField, DraftExpectationSource, DraftImportAcceptOut, DraftImportField, + DraftImportItem, DraftImportRun, DraftMetric, DraftOperation, DraftTrialMetric, DraftTrialOut, DraftTrialValidation, + DraftValidationsOut, DraftValidationRecord, DraftValidationReview, NlChangeProposal, QualityReport, } from '../../typesLedger' const D = LEDGER_UI.drafts +/** 业务规则(K04 的能力 + K06 的改法)的文案 */ +const R = LEDGER_UI.rules +/** 验证与审阅(K05 的记录)的文案 */ +const V = LEDGER_UI.validation +/** 文档更新 / 增量重导入(K11)的文案 */ +const I = LEDGER_UI.imports +/** 用一句话改口径(K12)的文案 */ +const N = LEDGER_UI.nl /** 列表按阶段筛:全部、起草中、待审、已丢弃、失败;细状态不再单独占筛选项 */ type Filter = '' | CaliberDraftStage @@ -44,6 +80,18 @@ const stageOf = (draft: CaliberDraftSummary | CaliberDraft): CaliberDraftStage = const DRAFT_POLL_MS = 2_000 const DRAFT_POLL_LIMIT_MS = 15 * 60_000 +/** 验证记录默认摆最近几条,其余收在「展开其余 N 条」后面 */ +const RECORDS_SHOWN = 3 + +/** + * 幂等键(K02):服务端按「主体 + 工作流 + 目标卡 + request_id」认这一次修改。同一批勾选的问题反复提交(网络 + * 断了、手点重试)用同一个键,服务端认得出是同一件事、不会多存一版;勾选或草稿变了才换一个。 + */ +const newRequestId = () => + typeof crypto !== 'undefined' && 'randomUUID' in crypto + ? crypto.randomUUID() + : `patch-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}` + /** 阶段标签:起草中 / 待审 / 已丢弃 / 起草失败;细状态放在 title 里,鼠标悬停能看到「待确认问题」这类差别 */ function StatusPill({ stage, status }: { stage: CaliberDraftStage; status?: CaliberDraftStatus }) { const color = stage === 'review' @@ -179,6 +227,264 @@ function entryInputs(fields: DraftEntryField[], values: Record): return inputs } +// ---------------------------------------------------------------- K06:业务规则、变更预览、验证记录 + +/** 业务值的说法:能力描述给了机器值 → 给人看的说法就用它,没有就照原样写 */ +const choiceLabel = (field: DraftEditableField | undefined, value: string): string => + field?.value_labels?.[value] ?? value + +/** 一个值转成页面上的一行文字:字符串照写,数字、布尔照写,对象转成 JSON 文本 */ +function valueText(value: unknown): string { + if (value == null) return '' + if (typeof value === 'string') return value + if (typeof value === 'number' || typeof value === 'boolean') return String(value) + const text = JSON.stringify(value) + return text ?? String(value) +} + +/** + * 表单初值:这一项在**所有**声明它的指标上写法一致时就是那个值,不一致(或没人声明)时留空。 + * 留空表示「保持各自现在的写法」——不替人选一个默认值,也就不会因为打开页面就凭空改掉谁。 + */ +function ruleInitialValues(binding?: DraftBinding): Record { + const out: Record = {} + if (!binding) return out + const declared = Object.values(binding.metric_values ?? {}) + for (const field of binding.editable_fields ?? []) { + const seen = new Set(declared.map((values) => values[field.field]).filter((value): value is string => !!value)) + out[field.field] = seen.size === 1 ? [...seen][0] : '' + } + return out +} + +/** 这一项这些指标里有没有人声明:一个都没有时这一项改不了(没有落点的取数不会被硬改) */ +const declaringMetrics = (binding: DraftBinding | undefined, field: string): string[] => + Object.entries(binding?.metric_values ?? {}) + .filter(([, values]) => !!values[field]).map(([metricId]) => metricId) + +/** 这次选中的写法会改到哪几条指标、每条从什么变成什么:只有声明了这一项、而且写法和选中的不一样才算 */ +function rulePlan(binding: DraftBinding | undefined, values: Record) { + const operations: DraftOperation[] = [] + const changes: { metricId: string; name: string; field: DraftEditableField; from: string; to: string }[] = [] + for (const field of binding?.editable_fields ?? []) { + const chosen = values[field.field] ?? '' + if (!chosen) continue + for (const [metricId, declared] of Object.entries(binding?.metric_values ?? {})) { + const now = declared[field.field] + if (!now || now === chosen) continue + operations.push({ op: 'set', metric_id: metricId, path: `/${field.field}`, value: chosen }) + changes.push({ metricId, name: '', field, from: now, to: chosen }) + } + } + return { operations, changes } +} + +/** + * 撤销这次修改要提交的逆操作:按**保存前**每一条指标声明的值构造——原来有值就设回去,原来没声明就删掉。 + * 撤销和保存一样是新增一版(当前版本 + 新的请求键),不整份覆盖、不改写已经存下的版本。 + */ +function undoOperations(binding: DraftBinding | undefined, operations: DraftOperation[]): DraftOperation[] { + return operations.map((op) => { + const field = op.path.replace(/^\//, '') + const before = binding?.metric_values?.[op.metric_id]?.[field] + return before + ? { op: 'set', metric_id: op.metric_id, path: op.path, value: before } + : { op: 'remove', metric_id: op.metric_id, path: op.path } + }) +} + +// ---------------------------------------------------------------- K11 / K12:字段的说法、三方值、一句话的影响 + +/** + * 字段路径 → 给人看的标签(K03 白名单和 app/ledger/changes.FIELDS 同一套,业务字段另有能力描述里的标签)。 + * 页面上只写这些业务说法,路径本身不上来。 + */ +const FIELD_LABELS: Record = { + '/synonyms': '同义词', + '/unit': '单位', + '/decimals': '小数位', + '/format': '展示格式', + '/expression': '取值表达式', + '/grain': '粒度', + '/time_field': '时间字段', + '/numerator': '分子', + '/denominator': '分母', + '/dimensions': '维度', + '/filters': '过滤条件', + '/definition/text': '口径说明', + '/definition/scope': '适用范围', + '/definition/exclusions': '不包含', + '/definition/citations': '引用原文', + '/time_role': '统计时间口径', + '/refund_rule': '退款处理', +} +/** 引用原文在 B / L / R 里是一段带段落 id 的结构化内容:只写有几段,不摆内容 */ +const CITATIONS_PATH = '/definition/citations' + +const fieldLabel = (path: string, binding?: DraftBinding): string => { + const name = path.replace(/^\//, '') + const editable = (binding?.editable_fields ?? []).find((field) => field.field === name) + return editable?.label ?? FIELD_LABELS[path] ?? I.otherField +} + +/** 业务字段的机器值 → 给人看的说法(能力描述里有就用它,没有就照原样写) */ +const valueLabelOf = (value: unknown, binding?: DraftBinding, path?: string): string => { + if (value == null) return I.noValue + if (typeof value === 'boolean') return value ? '是' : '否' + if (typeof value === 'number') return String(value) + if (typeof value === 'string') { + const name = String(path ?? '').replace(/^\//, '') + const editable = (binding?.editable_fields ?? []).find((field) => field.field === name) + return editable?.value_labels?.[value] ?? value + } + if (Array.isArray(value)) { + if (path === CITATIONS_PATH) return I.citationCount(value.length) + const parts = value.map((item) => valueLabelOf(item, binding, path)) + return parts.length ? parts.join('、') : I.emptyValue + } + if (typeof value === 'object') return I.objectValue + return String(value) +} + +/** 一格的一行字:这一格没有时返回 null(整行不画),不把「没有这一格」写成空值 */ +function cellText(cell: DraftImportField, which: 'b' | 'l' | 'r', binding?: DraftBinding): string | null { + const present = which === 'b' ? cell.b_present : which === 'l' ? cell.l_present : cell.r_present + if (!present) return null + return valueLabelOf(cell[which], binding, cell.path) +} + +/** 选中的格子:一条工作项 + 一条字段路径(未对齐的工作项没有可接受的字段,拒绝对齐前不能选) */ +const pickKey = (itemId: string, path: string): string => `${itemId}\u0000${path}` + +/** + * 这条工作项上「无冲突更新 + 新增候选」的格子:一次收掉的按钮按它算有几格,并把这几格**明确列给服务端** + * (不发 auto:页面列了几格就只接受几格)。已经接受 / 拒绝过的格子不再算进来,抽坏了的工作项一个也不收。 + */ +const cleanPaths = (item: DraftImportItem): string[] => + itemFailed(item) ? [] : item.fields.filter((cell) => (cell.state === 'update' || cell.state === 'new') + && cell.decided !== 'accepted' && cell.decided !== 'rejected').map((cell) => cell.path) + +/** 服务端标的「这条抽坏了」(引用没有给过模型的原文):也可能是老服务端只给了状态 */ +const itemFailed = (item: DraftImportItem): boolean => item.failed ?? item.status === 'failed' + +/** 这个工作项现在能不能接受:抽坏了的(failed)、没对齐上的,一律不能 */ +const itemAccepts = (item: DraftImportItem): boolean => !itemFailed(item) && !!item.metric_id + +/** + * 按这一次导入**现在**的现状裁掉不再适用的选择:格子没了、已经决定过、不能接受、工作项抽坏了的都不留下。 + * stale 之后重新读回现状时用它——不拿旧的选择去提交(旧的选择可能对着已经变了的 L)。 + */ +function prunePicks(picks: Record, run: DraftImportRun): + Record { + const out: Record = {} + for (const item of run.items) { + for (const cell of item.fields) { + const choice = picks[pickKey(item.item_id, cell.path)] + if (!choice || cell.decided != null) continue + if (choice === 'accept' && (!itemAccepts(item) || !cell.acceptable)) continue + out[pickKey(item.item_id, cell.path)] = choice + } + } + return out +} + +/** 还没处置完的工作项:恢复只对这些有意义(已接受 / 拒绝 / 不变的不动) */ +const unfinishedItems = (run: DraftImportRun): number => + run.items.filter((item) => !['accepted', 'rejected', 'unchanged'].includes(item.status)).length + +/** 一句话提案里的一处影响:哪条指标、哪一项写法、现在什么 → 保存后什么(页面上只写业务说法) */ +interface NlChange { + metricId: string + name: string + label: string + from: string + to: string + remove: boolean +} + +/** 提案里的字段操作 → 人读得懂的影响:指标名 + 字段标签 + 前后值,不摆 path / metric_id / JSON */ +function nlChanges(draft: CaliberDraft, operations: DraftOperation[]): NlChange[] { + const metrics = new Map((draft.metrics ?? []).filter((metric) => metric.id).map((metric) => [metric.id as string, metric])) + return (operations ?? []).map((operation) => { + const name = operation.path.replace(/^\//, '') + const metric = metrics.get(operation.metric_id) + const declared = draft.binding?.metric_values?.[operation.metric_id]?.[name] + ?? (metric ? (metric as unknown as Record)[name] : undefined) + const remove = operation.op === 'remove' + return { + metricId: operation.metric_id, + name: metric?.name ?? N.unknownMetric, + label: fieldLabel(operation.path, draft.binding), + from: valueLabelOf(declared, draft.binding, operation.path), + to: remove ? N.removeValue : valueLabelOf(operation.value, draft.binding, operation.path), + remove, + } + }) +} + +/** + * 落版之后服务端交回的操作和预览里的是不是同一批(按「改哪条指标的哪个字段、怎么改」比)。 + * 同一段原文应当解析出同一批;不一样就说明页面显示的和实际落下的不是一回事,要照实提示。 + * 审计读不回来(老服务端不给这一段)时返回 null:判不了就说判不了,不假装一致。 + */ +function sameOperations(previewed: DraftOperation[], + applied: { op: string; metric_id: string; path: string }[] | undefined): boolean | null { + if (!applied) return null + const key = (op: { op: string; metric_id: string; path: string }) => `${op.op}|${op.metric_id}|${op.path}` + const before = [...new Set(previewed.map(key))].sort() + const after = [...new Set(applied.map(key))].sort() + return before.length === after.length && before.every((item, index) => item === after[index]) +} + +/** + * 独立期望里填的一格:整数、小数写成数,true / false 写成布尔,方括号花括号按 JSON 读,其余照字面写。 + * 服务端按**原值**比较(不做隐式舍入),这里也不替它换算。 + */ +function expectValue(text: string): unknown { + const trimmed = text.trim() + if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed) + if (trimmed === 'true' || trimmed === 'false') return trimmed === 'true' + if (trimmed.startsWith('[') || trimmed.startsWith('{')) { + try { return JSON.parse(trimmed) } catch { return trimmed } + } + return trimmed +} + +/** + * 试跑响应里的质量结论:只有服务端给了认得的状态才算一份质量报告。 + * stale / needs_input / running 这些分支的 validation 可能只有验证记录那一段、甚至什么都没有—— + * 读不到状态就是「没有质量结论」,不能当成通过(也不能拿一次试跑成功代替验证)。 + */ +function qualityReportOf(validation?: DraftTrialValidation | null): QualityReport | null { + const status = validation?.status + if (status !== 'pass' && status !== 'fail' && status !== 'unknown') return null + return { status, checks: validation?.checks ?? [] } +} + +/** + * 覆盖判断:**只有 === true 才算覆盖**。false 是不覆盖,null / 缺字段是判不了(读不到当前依据), + * 三者要在界面上分开写,不能把判不了默认成覆盖。 + */ +const coversText = (value: boolean | null | undefined): string => + value === true ? V.covers : value === false ? V.notCovers : V.coversUnknown + +/** + * 一条审阅的确认范围有没有盖住整条记录的全部指标:只确认了其中几条时不能写成整卡通过。 + * scope 空着(或者读数缺字段)一律按「没盖住」算——宁可不写通过,不替服务端把范围补全。 + */ +function scopeCovers(record: DraftValidationRecord, review: DraftValidationReview | null | undefined): boolean { + const scope = new Set(review?.scope ?? []) + const ids = record.metric_ids ?? [] + if (!ids.length) return scope.size > 0 + return ids.every((id) => scope.has(id)) +} + +/** 这条记录里没有被确认范围盖住的指标 */ +function uncoveredMetrics(record: DraftValidationRecord, review: DraftValidationReview | null | undefined): string[] { + const scope = new Set(review?.scope ?? []) + return (record.metric_ids ?? []).filter((id) => !scope.has(id)) +} + export function CaliberDrafts() { const [drafts, setDrafts] = useState(null) const [listError, setListError] = useState(null) @@ -227,6 +533,76 @@ export function CaliberDrafts() { const asked = useRef(new Set()) /** 连续点开两份草稿时,晚到的那次详情不覆盖现在打开的那份 */ const openSeq = useRef(0) + /** 这次「回答并移除」的幂等键:勾选或草稿变了才换(K02) */ + const pendingWrite = useRef<{ signature: string; requestId: string }>({ signature: '', requestId: '' }) + + /** K06 业务规则:表单里选中的写法(字段名 → 机器值;空串是「保持各自现在的写法」) */ + const [ruleValues, setRuleValues] = useState>({}) + /** 这次保存的幂等键:同一批字段操作反复提交用同一个键,选择变了才换 */ + const rulePending = useRef<{ signature: string; requestId: string }>({ signature: '', requestId: '' }) + const [ruleBusy, setRuleBusy] = useState<'save' | 'undo' | null>(null) + const [ruleError, setRuleError] = useState(null) + /** 写入被拒(基准版本过期):说清你基于哪一版、服务端现在是哪一版,选择一个字不动 */ + const [ruleStale, setRuleStale] = useState<{ current: number | null; base: number | null } | null>(null) + /** 这次保存(或撤销)的回执:换成哪一版、绑定同步到哪一步、旧验证怎么失效 */ + const [ruleResult, setRuleResult] = useState(null) + const [ruleReplayed, setRuleReplayed] = useState(false) + /** 撤销要提交的逆操作(按保存前的值构造)和这次改了几处 */ + const [undoRecord, setUndoRecord] = useState<{ operations: DraftOperation[]; count: number } | null>(null) + + /** K11 增量重导入:这份草稿的导入记录、正在看的那一次、逐格的选择和人工对齐 */ + const [importRuns, setImportRuns] = useState(null) + const [importsError, setImportsError] = useState(null) + const [importId, setImportId] = useState(null) + const [importBusy, setImportBusy] = useState(null) + const [importError, setImportError] = useState(null) + /** 逐格的选择:`itemId\0path` → accept / reject(没选的格子不动) */ + const [importPicks, setImportPicks] = useState>({}) + /** 没对齐的工作项要人工指定对哪条指标:item_id → metric_id(空串是取消对齐) */ + const [alignPicks, setAlignPicks] = useState>({}) + /** 接受被拒(基准版本过期 / 这次导入比的还是旧的 L):选好的格子一个不丢,说清你基于哪一版 */ + const [importStale, setImportStale] = useState<{ code: 'stale_revision' | 'import_stale_l' + current: number | null; base: number | null + /** 服务端点名的那几格(字段的给人看的说法),import_stale_l 时用来指名道姓 */ + names: string } | null>(null) + /** 这次接受 / 拒绝的回执 */ + const [importResult, setImportResult] = useState(null) + const [importAccepted, setImportAccepted] = useState(false) + const [importRejected, setImportRejected] = useState(false) + const [importNote, setImportNote] = useState('') + /** 接受的幂等键:同一批格子的接受反复提交用同一个键,选择变了才换 */ + const importRequest = useRef<{ signature: string; requestId: string }>({ signature: '', requestId: '' }) + /** 重新读取 / 恢复之后:queued、running 时每两秒取一次这一次导入 */ + const [importPollId, setImportPollId] = useState(null) + + /** K12 一句话改口径:输入、只读提案、这次落版的结果 */ + const [nlText, setNlText] = useState('') + const [nlPreview, setNlPreview] = useState(null) + /** 这份提案是哪一段原文产出来的:输入改过就必须重新预览,确认发的也是这一段 */ + const [nlPreviewOf, setNlPreviewOf] = useState('') + const [nlNotice, setNlNotice] = useState<'idle' | 'preview' | 'clarify' | 'applied'>('idle') + const [nlBusy, setNlBusy] = useState<'preview' | 'confirm' | null>(null) + const [nlError, setNlError] = useState(null) + const [nlResult, setNlResult] = useState<{ revision: number | null; invalidated: boolean; replayed: boolean + /** 服务端这次落下的操作和预览里的是不是同一批;null 是审计读不回来(判不了) */ + mismatch: boolean | null } | null>(null) + /** 确认落版用的幂等键:同一句话反复确认是同一件事(服务端认得出,不会多存一版) */ + const nlRequest = useRef<{ signature: string; requestId: string }>({ signature: '', requestId: '' }) + + /** K05 的验证记录:记录 + 总情况 + 字段基线状态,走单独那个接口取 */ + const [validations, setValidations] = useState(null) + const [validationsError, setValidationsError] = useState(null) + /** 刚做完的审阅:按记录 id 显示服务端交回的决定(谁、覆盖不覆盖),不等列表刷新 */ + const [reviewOut, setReviewOut] = useState>({}) + const [reviewNotes, setReviewNotes] = useState>({}) + const [reviewBusy, setReviewBusy] = useState(null) + const [reviewError, setReviewError] = useState(null) + /** 独立期望:每条指标一格,逐条给全才能提交 */ + const [expectValues, setExpectValues] = useState>({}) + const [expectSource, setExpectSource] = useState('human_confirmed') + /** 验证记录先摆最近几条,其余收起来 */ + const [recordsShown, setRecordsShown] = useState(RECORDS_SHOWN) + const canReview = useAtLeast('builder') const loadList = useCallback(() => { setListError(null) @@ -237,6 +613,40 @@ export function CaliberDrafts() { }, []) useEffect(loadList, [loadList]) + /** K05 的验证记录:记录、总情况、字段基线状态。读不到照实写「无法读取」,不当成「还没有记录」 */ + const loadValidations = useCallback((id: string) => { + const seq = openSeq.current + api.caliberLedger.draftValidations(id).then( + (out) => { if (seq === openSeq.current) { setValidations(out); setValidationsError(null) } }, + (e) => { if (seq === openSeq.current) { setValidations(null); setValidationsError(e) } }, + ) + }, []) + + /** 把一次导入的现状并回列表(新的在前):重新读取 / 恢复 / 对齐 / 接受 / 拒绝之后都用它 */ + const putImport = useCallback((run: DraftImportRun) => { + setImportRuns((cur) => [run, ...(cur ?? []).filter((row) => row.run_id !== run.run_id)]) + }, []) + + /** + * K11 的导入记录:新的在前,每条都带工作项和逐字段三方。还有正在跑的那一次就跟着轮询它 + * (重新读取是后台任务,页面只管取它的现状) + */ + const loadImports = useCallback((id: string) => { + const seq = openSeq.current + api.caliberLedger.imports(id).then( + (out) => { + if (seq !== openSeq.current) return + setImportRuns(out.runs) + setImportsError(null) + // 默认摆最近那一次的明细:记录列表点哪一次看哪一次 + setImportId((cur) => (cur && out.runs.some((run) => run.run_id === cur) ? cur : (out.runs[0]?.run_id ?? null))) + const running = out.runs.find((run) => run.status === 'queued' || run.status === 'running') + if (running) setImportPollId(running.run_id) + }, + (e) => { if (seq === openSeq.current) { setImportRuns(null); setImportsError(e) } }, + ) + }, []) + useEffect(() => { api.kb.documents().then((rows) => { setDocs(rows); setDocsError(null) }, (e) => { setDocs([]); setDocsError(e) }) @@ -280,6 +690,44 @@ export function CaliberDrafts() { setTrialTimedOut(false) setTrialError(null) setJobError(null) + setRuleValues({}) + setRuleBusy(null) + setRuleError(null) + setRuleStale(null) + setRuleResult(null) + setRuleReplayed(false) + setUndoRecord(null) + rulePending.current = { signature: '', requestId: '' } + setValidations(null) + setValidationsError(null) + setReviewOut({}) + setReviewNotes({}) + setReviewError(null) + setExpectValues({}) + setExpectSource('human_confirmed') + setRecordsShown(RECORDS_SHOWN) + setImportRuns(null) + setImportsError(null) + setImportId(null) + setImportBusy(null) + setImportError(null) + setImportPicks({}) + setAlignPicks({}) + setImportStale(null) + setImportResult(null) + setImportAccepted(false) + setImportRejected(false) + setImportNote('') + setImportPollId(null) + importRequest.current = { signature: '', requestId: '' } + setNlText('') + setNlPreview(null) + setNlPreviewOf('') + setNlNotice('idle') + setNlBusy(null) + setNlError(null) + setNlResult(null) + nlRequest.current = { signature: '', requestId: '' } try { const draft = await api.caliberLedger.draft(id) if (seq !== openSeq.current) return @@ -287,6 +735,8 @@ export function CaliberDrafts() { const marks: Record = {} setEntryValues(entryInitialValues(draft.entry_fields ?? [], marks)) setPrefilled(marks) + // 业务规则的初值按这次读到的能力描述定:写法一致的项直接显示,不一致的留空等人选 + setRuleValues(ruleInitialValues(draft.binding)) if (draft.status === 'drafting') { setPollTimedOut(false); setPollingId(id) } } catch (e) { if (seq !== openSeq.current) return @@ -294,12 +744,28 @@ export function CaliberDrafts() { } finally { if (seq === openSeq.current) setDetailLoading(false) } + loadValidations(id) + loadImports(id) api.runs.list({ status: 'succeeded', limit: 20 }).then( (runs) => { if (seq === openSeq.current) setRecentRuns(runs) }, () => { if (seq === openSeq.current) setRecentRuns([]) }, ) } + /** + * 只刷新详情,不重置页面(不清勾选、不动表单、不换打开的那份)。写入被拒之后用它:拿回服务端现在这一版 + * 当新的基准版本,人确认后再点一次就行(K02)。晚到的响应不覆盖已经切到别的草稿的那一份 + */ + const refreshDetail = useCallback(async (id: string) => { + const seq = openSeq.current + try { + const fresh = await api.caliberLedger.draft(id) + if (seq === openSeq.current) setDetail((cur) => (cur && cur.id === fresh.id ? fresh : cur)) + } catch { + // 读不到就先保持现在这一份:人下次动手时还会再取 + } + }, []) + useEffect(() => { if (!pollingId) return const until = Date.now() + DRAFT_POLL_LIMIT_MS @@ -369,6 +835,8 @@ export function CaliberDrafts() { setTrialPollId(null) setTrialTimedOut(false) loadList() + // 试运行到终态时服务端会把这次跑完的验证记录补记一条:跟着取一次,结论按记录说 + loadValidations(trialPollId) const seq = openSeq.current api.caliberLedger.draft(trialPollId).then((fresh) => { if (seq !== openSeq.current) return @@ -381,7 +849,33 @@ export function CaliberDrafts() { }) }, 2000) return () => { alive = false; clearInterval(timer) } - }, [trialPollId, loadList]) + }, [trialPollId, loadList, loadValidations]) + + /** + * 正在跑的那一次重导入:每两秒取一次现状(后台在抽候选、算三方),到终态就停。被中断的不会自动续跑, + * 页面上由人点「恢复」显式排回后台。 + */ + useEffect(() => { + if (!importPollId) return + const until = Date.now() + 5 * 60_000 + let alive = true + const timer = setInterval(() => { + api.caliberLedger.importRun(importPollId).then((run) => { + if (!alive) return + putImport(run) + if (run.status === 'queued' || run.status === 'running') { + if (Date.now() > until) setImportPollId(null) + return + } + setImportPollId(null) + }, (e) => { + if (!alive) return + setImportPollId(null) + setImportError(e) + }) + }, 2000) + return () => { alive = false; clearInterval(timer) } + }, [importPollId, putImport]) useEffect(() => { for (const doc of detail?.documents ?? []) ensureChunks(doc.document_id) @@ -435,15 +929,45 @@ export function CaliberDrafts() { const resolve = async (draft: CaliberDraft) => { if (!pickedQuestions.length) { toast.warn(D.resolveNeed); return } + // 已接管的草稿:改哪张卡要明确(详情接口给的 card_id);图上有多张可写的卡又认不出唯一目标时不给改, + // 免得按「第一张」猜(K02) + if (draft.revision != null && draft.workflow_id && !draft.card_id) { + toast.warn(draft.cards && draft.cards.length > 1 ? D.cardAmbiguous : D.cardMissing) + return + } setBusy(`resolve:${draft.id}`) + // 消问题是按集合做的:去空白、去重、排序之后再发,勾选顺序变一下不该被当成另一次请求(K02 的幂等指纹 + // 服务端也按同一份归一算) + const questions = [...new Set(pickedQuestions.map((q) => q.trim()).filter(Boolean))].sort() + // 同一批勾选反复提交(网络失败后重试)用同一个幂等键:服务端认得出是同一件事,不会多存一版 + const signature = `${draft.id}|${questions.join('\u0000')}` + if (pendingWrite.current.signature !== signature) { + pendingWrite.current = { signature, requestId: newRequestId() } + } try { - const fresh = await api.caliberLedger.patchDraft(draft.id, { resolved: pickedQuestions }) + const fresh = await api.caliberLedger.patchDraft(draft.id, { + resolved: questions, + ...(draft.revision != null ? { expected_revision: draft.revision } : {}), + ...(draft.card_id ? { target: { workflow_id: draft.workflow_id ?? undefined, card_id: draft.card_id } } : {}), + request_id: pendingWrite.current.requestId, + }) setDetail(fresh) - toast.ok(D.resolved(pickedQuestions.length)) + toast.ok(D.resolved(questions.length)) setPickedQuestions([]) + // 这一批已经落库:换一个键,别让下一次(重新勾选)落到同一个幂等键上 + pendingWrite.current = { signature: '', requestId: '' } loadList() } catch (e) { - toast.error(e) + const stale = e instanceof ApiError && e.status === 409 && e.code === 'stale_revision' + if (stale) { + // 有人在别处先改过:这次没写进去,勾选一个不丢、也不拿新版本自动重发;说清现况,人确认后再点一次 + const told = Number((e.body as { current_version?: unknown } | undefined)?.current_version) + toast.warn(D.writeStale(Number.isFinite(told) ? told : null, draft.revision ?? null)) + // 只把详情刷到最新(拿新的基准版本),不清空勾选、不重置页面 + void refreshDetail(draft.id) + } else { + toast.error(e) + } } finally { setBusy(null) } @@ -527,19 +1051,24 @@ export function CaliberDrafts() { ) } - /** 按填好的入口字段再试运行一次:自动试跑缺必填输入时停在 needs_input,人在这里补上 */ - const runTrial = async (draft: CaliberDraft) => { + /** + * 按填好的入口字段再试运行一次:自动试跑缺必填输入时停在 needs_input,人在这里补上。 + * 带 expect 时这一条会落成一条带独立期望的验证记录(对得上就是对得上,对不上照实记);不带就是只记试跑结果。 + * 入口字段的写法变化只影响这一次请求的参数,不会创建口径定义版本。 + */ + const runTrial = async (draft: CaliberDraft, expect?: { metrics: Record; source: DraftExpectationSource }) => { const fields = draft.entry_fields ?? [] if (!entryReady(fields, entryValues)) return setTrialStarting(true) setTrialError(null) try { - const out = await api.caliberLedger.runDraftTrial(draft.id, entryInputs(fields, entryValues)) + const out = await api.caliberLedger.runDraftTrial(draft.id, entryInputs(fields, entryValues), expect) setTrial(out) setTrialTimedOut(false) if (out.status === 'running' && out.run_id) setTrialPollId(draft.id) const fresh = await api.caliberLedger.draft(draft.id) setDetail((cur) => cur?.id === fresh.id ? fresh : cur) + loadValidations(draft.id) } catch (e) { setTrialError(e) } finally { @@ -547,6 +1076,391 @@ export function CaliberDrafts() { } } + /** + * 保存这次业务规则的修改:把**所有**受影响指标的字段操作放在一次请求里(PATCH 的 operations),带上读到的 + * 基准版本、目标卡和幂等键。一次原子变更:全成或全不成;回执(change)说清落成哪一版、绑定同步到哪一步。 + * 被拒(基准版本过期)时什么都不改:这里的写法选择留着,刷新详情拿到新版本后由人显式再点一次。 + */ + const saveRules = async (draft: CaliberDraft, operations: DraftOperation[]) => { + if (!operations.length) { toast.warn(R.saveNeedChange); return } + if (!draft.card_id || draft.revision == null) { toast.warn(R.noCard); return } + setRuleBusy('save') + setRuleError(null) + // 同一批操作反复提交(网络断了、手点重试)用同一个幂等键:服务端认得出是同一件事,不会多存一版 + const signature = `${draft.id}|${JSON.stringify(operations)}` + if (rulePending.current.signature !== signature) { + rulePending.current = { signature, requestId: newRequestId() } + } + try { + const fresh = await api.caliberLedger.patchDraft(draft.id, { + operations, + expected_revision: draft.revision, + request_id: rulePending.current.requestId, + target: { workflow_id: draft.workflow_id ?? undefined, card_id: draft.card_id }, + }) + setDetail(fresh) + setRuleResult(fresh.change ?? null) + setRuleReplayed(!!fresh.replayed) + setRuleStale(null) + // 撤销按**保存前**那份能力描述里的值构造逆操作,所以用这一版的 binding,不用刚回来的 + setUndoRecord({ operations: undoOperations(draft.binding, operations), count: operations.length }) + setRuleValues(ruleInitialValues(fresh.binding)) + rulePending.current = { signature: '', requestId: '' } + toast.ok(R.saved(fresh.change?.revision ?? fresh.revision ?? null)) + loadValidations(draft.id) + loadList() + } catch (e) { + const stale = e instanceof ApiError && e.status === 409 && e.code === 'stale_revision' + if (stale) { + // 有人在别处先改过:这次没写进去,选择一个不丢、也不拿新版本自动重发;刷新详情只是为了拿到新的基准版本 + const told = Number((e.body as { current_version?: unknown } | undefined)?.current_version) + setRuleStale({ current: Number.isFinite(told) ? told : null, base: draft.revision ?? null }) + void refreshDetail(draft.id) + } else { + setRuleError(e) + } + } finally { + setRuleBusy(null) + } + } + + /** 撤销这次修改:逆操作 + 当前版本 + 新的请求键,再新增一版;不是整份覆盖,也不改已经存下的版本 */ + const undoRules = async (draft: CaliberDraft, record: { operations: DraftOperation[]; count: number }) => { + if (draft.revision == null || !record.operations.length) return + setRuleBusy('undo') + setRuleError(null) + // 撤销也按内容认一次:网络断了再点一次是同一件事,服务端认得出,不会多存一版 + const signature = `undo|${draft.id}|${JSON.stringify(record.operations)}` + if (rulePending.current.signature !== signature) { + rulePending.current = { signature, requestId: newRequestId() } + } + try { + const fresh = await api.caliberLedger.patchDraft(draft.id, { + operations: record.operations, + expected_revision: draft.revision, + request_id: rulePending.current.requestId, + target: { workflow_id: draft.workflow_id ?? undefined, card_id: draft.card_id ?? undefined }, + }) + setDetail(fresh) + setRuleResult(fresh.change ?? null) + setRuleReplayed(!!fresh.replayed) + setRuleStale(null) + setUndoRecord(null) + setRuleValues(ruleInitialValues(fresh.binding)) + rulePending.current = { signature: '', requestId: '' } + toast.ok(R.undone(fresh.change?.revision ?? fresh.revision ?? null)) + loadValidations(draft.id) + loadList() + } catch (e) { + const stale = e instanceof ApiError && e.status === 409 && e.code === 'stale_revision' + if (stale) { + const told = Number((e.body as { current_version?: unknown } | undefined)?.current_version) + setRuleStale({ current: Number.isFinite(told) ? told : null, base: draft.revision ?? null }) + void refreshDetail(draft.id) + } else { + setRuleError(e) + } + } finally { + setRuleBusy(null) + } + } + + /** + * 重新读一遍文档(K11):在服务端重抽候选 R,和现在的内容 L、上次被接受的导入值 B 逐字段比。 + * **不改 L、不改 B**——真正落到图上的只有下面的「接受选定字段」。带幂等键:同一份草稿 + 同一个键只建一次。 + */ + const createImport = async (draft: CaliberDraft) => { + if (!draft.workflow_id) { toast.warn(I.readOnly); return } + setImportBusy('create') + setImportError(null) + setImportStale(null) + setImportResult(null) + setImportAccepted(false) + setImportRejected(false) + const signature = `import|${draft.id}|${draft.revision ?? ''}` + if (importRequest.current.signature !== signature) { + importRequest.current = { signature, requestId: newRequestId() } + } + try { + const run = await api.caliberLedger.createImport(draft.id, importRequest.current.requestId) + putImport(run) + setImportId(run.run_id) + setImportPicks({}) + setAlignPicks({}) + importRequest.current = { signature: '', requestId: '' } + if (run.status === 'queued' || run.status === 'running') setImportPollId(run.run_id) + toast.ok(I.started) + } catch (e) { + setImportError(e) + } finally { + setImportBusy(null) + } + } + + /** + * 人工把一条工作项对到图上某条指标(空串是取消对齐)。baseline_unknown 的每一条、还有同名不同范围(引的原文 + * 不是同一段)都要人在这里定:机器不按名字猜「这说的是同一条指标」。对齐只重算三方,不改 L、不改 B。 + */ + const alignImportItem = async (run: DraftImportRun, item: DraftImportItem, metricId: string) => { + setImportBusy(`align:${item.item_id}`) + setImportError(null) + try { + const fresh = await api.caliberLedger.alignImportItem(run.run_id, item.item_id, metricId) + putImport(fresh) + // 换了对哪一条,这条上旧的选择就不适用了:只清这一条的,别的地方不动 + setImportPicks((cur) => { + const next: Record = {} + for (const [key, value] of Object.entries(cur)) if (!key.startsWith(`${item.item_id}\u0000`)) next[key] = value + return next + }) + } catch (e) { + setImportError(e) + } finally { + setImportBusy(null) + } + } + + /** + * 重新读一次这一次导入的现状:逐字段的三方(B / L / R)是服务端按**现在**的图现算的,重新读才知道自己看的 + * 还是不是最新的。顺手把不再适用的选择裁掉——不拿旧的选择去提交。 + */ + const reloadImportRun = useCallback(async (runId: string): Promise => { + try { + const fresh = await api.caliberLedger.importRun(runId) + putImport(fresh) + setImportPicks((cur) => prunePicks(cur, fresh)) + return fresh + } catch (e) { + setImportError(e) + return null + } + }, [putImport]) + + /** + * 服务端说这次导入比对的还是旧的 L(409 import_stale_l)之后的恢复:按**现在的** L / B 重算这次导入还没决定的 + * 三方(人处置过的决定不动),把现状交回来。不能只把基准版本更新到最新一版就覆盖上去。 + */ + const refreshImportRun = useCallback(async (runId: string): Promise => { + try { + const fresh = await api.caliberLedger.refreshImport(runId) + putImport(fresh) + setImportPicks((cur) => prunePicks(cur, fresh)) + return fresh + } catch (e) { + setImportError(e) + return null + } + }, [putImport]) + + /** + * 接受选定的格子:一次提交(带读到的基准版本和幂等键)→ 图新增一版 + 按被接受的格子推进 B。 + * 每条按**工作项身份**(item_id)指认,带上要落的那条指标和**明确列出来的**字段路径;不是这里列出来的格子, + * 一个都不动。被拒(基准版本过期、或者这次比对的是旧的 L)时选好的格子原样留着,先把这一次导入的现状重新读 + * 回来再让人决定——不拿旧 L 直接覆盖。 + */ + const acceptImportFields = async (draft: CaliberDraft, run: DraftImportRun, + items: { item_id: string; metric_id?: string; fields: string[] }[]) => { + const picked = items.filter((item) => item.fields.length) + if (!picked.length) { toast.warn(I.nothingSelected); return } + if (draft.revision == null) { toast.warn(I.needRevision); return } + setImportBusy('accept') + setImportError(null) + setImportStale(null) + setImportResult(null) + setImportRejected(false) + const signature = `accept|${run.run_id}|${JSON.stringify(picked)}` + if (importRequest.current.signature !== signature) { + importRequest.current = { signature, requestId: newRequestId() } + } + try { + const out = await api.caliberLedger.acceptImport(run.run_id, { + items: picked, expected_revision: draft.revision, request_id: importRequest.current.requestId, + }) + putImport(out) + setImportResult(out) + setImportAccepted(true) + setImportPicks({}) + importRequest.current = { signature: '', requestId: '' } + toast.ok(I.accepted(out.revision)) + // 图和 B 是同一次提交里推进的:详情、验证状态和列表都跟着刷 + void refreshDetail(draft.id) + loadValidations(draft.id) + loadList() + } catch (e) { + const code = e instanceof ApiError && e.status === 409 ? e.code : null + if (code === 'stale_revision' || code === 'import_stale_l') { + const body = e instanceof ApiError ? (e.body as { current_version?: unknown + fields?: { path?: string }[] } | undefined) : undefined + const told = Number(body?.current_version) + // 服务端点名的就是这几格:把字段说法列出来,人一眼看出是哪一格对不上了 + const names = (body?.fields ?? []).map((row) => fieldLabel(String(row.path ?? ''), draft.binding)).join('、') + setImportStale({ + code: code === 'import_stale_l' ? 'import_stale_l' : 'stale_revision', + current: Number.isFinite(told) ? told : null, base: draft.revision ?? null, names, + }) + // 写不进去:先把这一次导入的现状重新读回来,再读一次详情拿新的基准版本。 + // import_stale_l 是「三方算的是旧的 L」:按现在的 L / B **重算三方**(refresh),不是只更新版本号就覆盖。 + if (code === 'import_stale_l') await refreshImportRun(run.run_id) + else await reloadImportRun(run.run_id) + void refreshDetail(draft.id) + } else { + setImportError(e) + } + } finally { + setImportBusy(null) + } + } + + /** 拒绝选定的格子:保持 L 不动,也不推进 B。同样按工作项身份指认,只拒这里明确列出来的格子 */ + const rejectImportFields = async (run: DraftImportRun, + items: { item_id: string; metric_id?: string; seq?: number; fields: string[] }[]) => { + const picked = items.filter((item) => item.fields.length) + if (!picked.length) { toast.warn(I.nothingSelected); return } + setImportBusy('reject') + setImportError(null) + setImportResult(null) + setImportAccepted(false) + try { + const fresh = await api.caliberLedger.rejectImport(run.run_id, { + items: picked, ...(importNote.trim() ? { note: importNote.trim() } : {}), + }) + putImport(fresh) + setImportRejected(true) + setImportPicks({}) + } catch (e) { + setImportError(e) + } finally { + setImportBusy(null) + } + } + + /** 显式恢复被中断的那一次导入:续做还没完成的工作项,已接受 / 拒绝的不动、不重复建版 */ + const resumeImportRun = async (run: DraftImportRun) => { + setImportBusy('resume') + setImportError(null) + try { + const fresh = await api.caliberLedger.resumeImport(run.run_id) + putImport(fresh) + setImportPollId(fresh.run_id) + toast.ok(I.resumed) + } catch (e) { + setImportError(e) + } finally { + setImportBusy(null) + } + } + + /** + * 用一句话看影响(K12):只调**只读**的提案接口,不落库、不新增版本。认出来的条件落成 K03 同一形状的 operations, + * 这里只把它翻成「哪条指标、哪一项写法、现在什么 → 保存后什么」;说不清时只有澄清项,一条操作都不产出。 + * + * 提案和**产出它的那一段原文**一起记下来(nlPreviewOf):确认时按那一段原文发、服务端再解析一次得到的还是同一批 + * 操作;页面显示的(A)和实际落下的(B)不会是两句不同的话。 + */ + const previewNl = async (draft: CaliberDraft) => { + const instruction = nlText.trim() + if (!instruction) { toast.warn(N.needText); return } + if (!draft.card_id) { toast.warn(draft.cards && draft.cards.length > 1 ? D.cardAmbiguous : D.cardMissing); return } + setNlBusy('preview') + setNlError(null) + setNlResult(null) + setNlPreview(null) + try { + const out = await api.caliberLedger.changeProposal(draft.id, { + instruction, + target: { workflow_id: draft.workflow_id ?? undefined, card_id: draft.card_id }, + }) + setNlPreview(out.proposal) + setNlPreviewOf(instruction) + setNlNotice(out.proposal.ready ? 'preview' : 'clarify') + // 同一句话反复确认是同一件事:请求键按内容定,重发不会多存一版 + const signature = `nl|${draft.id}|${instruction}` + if (nlRequest.current.signature !== signature) { + nlRequest.current = { signature, requestId: newRequestId() } + } + } catch (e) { + setNlNotice('idle') + setNlError(e) + } finally { + setNlBusy(null) + } + } + + /** + * 确认之后才落版(K12):confirm=true 走服务端的薄适配,内部仍是现有变更服务(版本 CAS、幂等键、绑定同步、 + * 校验一条不少)。 + * + * 发出去的是**预览时那一段原文**,不是输入框里现在的内容:输入改过就必须重新预览(nlTouched),否则页面显示的 + * 是 A、落下的会是 B。落版之后另比一次服务端落下的操作和预览里的是不是同一批,不一样就照实提示。 + * 失败时页面上什么都不改——输入和预览都留着,由人决定下一步。 + */ + const confirmNl = async (draft: CaliberDraft) => { + if (!nlPreviewOf || !nlPreview?.ready) { toast.warn(N.needConfirm); return } + if (nlText.trim() !== nlPreviewOf) { toast.warn(N.needPreviewAgain); return } + if (draft.revision == null) { toast.warn(N.noRevision); return } + setNlBusy('confirm') + setNlError(null) + const signature = `nl|${draft.id}|${nlPreviewOf}` + if (nlRequest.current.signature !== signature) { + nlRequest.current = { signature, requestId: newRequestId() } + } + try { + const out = await api.caliberLedger.nlChange(draft.id, { + instruction: nlPreviewOf, + confirm: true, + expected_revision: draft.revision, + request_id: nlRequest.current.requestId, + target: { workflow_id: draft.workflow_id ?? undefined, card_id: draft.card_id ?? undefined }, + }) + const fresh = 'proposal' in out ? null : out + const revision = fresh?.change?.revision ?? fresh?.revision ?? null + // 服务端这次落下的操作和预览里的是不是同一批(同一段原文应当解析出同一批);判不了就是 null + const same = sameOperations(nlPreview.operations, fresh?.change?.operations) + setNlResult({ + revision, + invalidated: fresh?.change?.validation?.invalidated ?? false, + replayed: !!fresh?.replayed, + mismatch: same === null ? null : !same, + }) + setNlNotice('applied') + nlRequest.current = { signature: '', requestId: '' } + toast.ok(N.applied(revision)) + if (fresh) { + setDetail((cur) => (cur && cur.id === fresh.id ? fresh : cur)) + setRuleValues(ruleInitialValues(fresh.binding)) + } + loadValidations(draft.id) + loadList() + } catch (e) { + setNlError(e) + } finally { + setNlBusy(null) + } + } + + /** + * 对一条验证记录做审阅:只调服务端那个接口(审批人由服务端身份定,界面代写不了),拿回来的决定照原样显示 + * ——谁、什么时候、覆盖不覆盖当前版本。样例对得上不会自动变成批准,这里也不在前端改结论。 + */ + const reviewRecord = async (draft: CaliberDraft, recordId: string, decision: 'confirmed' | 'rejected') => { + setReviewBusy(recordId) + setReviewError(null) + try { + const note = (reviewNotes[recordId] ?? '').trim() + const out = await api.caliberLedger.reviewValidation(draft.id, recordId, + { decision, ...(note ? { note } : {}) }) + setReviewOut((cur) => ({ ...cur, [recordId]: out.record.review ?? null })) + setReviewNotes((cur) => ({ ...cur, [recordId]: '' })) + toast.ok(V.reviewDone(decision === 'confirmed' ? V.reviewConfirmed : V.reviewRejected)) + loadValidations(draft.id) + void refreshDetail(draft.id) + } catch (e) { + setReviewError(e) + } finally { + setReviewBusy(null) + } + } + const changeDraftJob = async (draft: CaliberDraft, action: 'retry' | 'stop') => { const seq = openSeq.current setJobBusy(draft.id) @@ -568,12 +1482,876 @@ export function CaliberDrafts() { } } + /** + * 业务规则(K06 的工作台):服务端的能力描述说得出这张卡能按字段改哪几项时才开表单。改完先列「会改到哪几条指标、 + * 现在什么写法 → 保存后什么写法」,再把所有受影响指标的字段操作**一次**提交(原子变更);回执说清落成哪一版、 + * 取数同步到哪一步、旧验证怎么失效,并按保存前的值给出「撤销这次修改」。这块只写业务说法:取数语句、内部编号、 + * 字段路径和 JSON 都不上来。 + */ + const renderRules = (draft: CaliberDraft) => { + const binding = draft.binding + if (!binding) return null + const fields = binding.editable_fields ?? [] + const metrics = (draft.metrics ?? []).filter((metric) => metric.id) + const names = new Map(metrics.map((metric) => [metric.id as string, metric.name])) + const declared = new Set(Object.keys(binding.metric_values ?? {})) + const plan = rulePlan(binding, ruleValues) + const changes = plan.changes.map((change) => ({ ...change, name: names.get(change.metricId) ?? change.metricId })) + const readOnly = !draft.workflow_id ? R.noWorkflow + : !draft.card_id ? R.noCard + : draft.revision == null ? R.noRevision + : declared.size === 0 ? R.unbound : null + const label = R.status[binding.status] ?? binding.status + const tone = binding.status === 'aligned' ? 'var(--ok)' + : binding.status === 'unbound' ? 'var(--text-faint)' : 'var(--warn)' + const saved = ruleResult?.binding + const untouched = metrics.length - declared.size + return ( +
+
+

{R.title}

+ {label} + {R.hint} +
+ {binding.status === 'aligned' ? ( +

{R.alignedNote}

+ ) : ( + <> +

+ {R.reason}:{binding.reason} +

+ {binding.fix && binding.fix !== 'none' && ( +

+ {R.fixLabel}:{R.fix[binding.fix] ?? binding.fix} +

+ )} + + )} + + {readOnly ? ( +

{R.readOnly}:{readOnly}

+ ) : ( + <> +
    + {fields.map((field) => { + const declaring = declaringMetrics(binding, field.field) + const distinct = [...new Set(declaring.map((id) => binding.metric_values[id][field.field]))] + const chosen = ruleValues[field.field] ?? '' + return ( +
  • + {field.label} + + + {!declaring.length ? R.fieldNone + : distinct.length > 1 ? R.mixed + : `${R.before}:${choiceLabel(field, distinct[0])}`} + + {field.help} +
  • + ) + })} +
+ {untouched > 0 && ( +

+ {R.unaffected(untouched)}。{R.unaffectedHint} +

+ )} + +
+
+ {R.previewTitle} + + {changes.length ? R.affected(changes.length) : R.noChange} + +
+ {changes.length > 0 && ( +
    + {changes.map((change) => ( +
  • + {change.name} + · {change.field.label}: + {choiceLabel(change.field, change.from)} + → + {choiceLabel(change.field, change.to)} +
  • + ))} +
+ )} +
+ +
+ + {undoRecord && ( + + )} +
+ + )} + + {ruleStale && ( +
+ {R.stale(ruleStale.current, ruleStale.base)} +
+ )} + {ruleError != null &&
} + {ruleReplayed && !ruleResult && ( +
{R.replayed}
+ )} + + {ruleResult && ( +
+

+ {R.saved(ruleResult.revision)} + {ruleReplayed && · {R.replayed}} +

+ {ruleResult.applied ? ( + <> +

+ {saved?.synced ? R.savedAligned : R.savedNotSynced} + {!saved?.synced && saved?.reason ? `(${saved.reason})` : ''} +

+

{R.invalidated}

+

{R.nextStep}

+ {!saved?.synced && saved?.fix && saved.fix !== 'none' && ( +

+ {R.fixLabel}:{R.fix[saved.fix] ?? saved.fix}。{R.fixNote} +

+ )} + + ) : ( +

{R.savedNoChange}

+ )} +
+ )} +
+ ) + } + + /** + * 文档更新(K11 的增量重导入):重抽候选 R,和现在的内容 L、上次被接受的导入值 B 逐字段比。R 只是候选—— + * 落到图上只有「接受选定字段」这一次显式动作(一次提交里新增一版图 + 按被接受的格子推进 B)。逐格写清三方 + * 的值、状态和为什么;漏提取不当删除(不能接受,L 上的原值原样留着);没对齐上的工作项由人指定对到哪条指标。 + * 提交一律按**工作项身份**(item_id)指认、把要落的那几格**明确列出来**(不发 auto);抽坏了的(failed)工作项 + * 一个接受都点不了,批量也不收它;已接受 / 拒绝过的格子不再被选。被中断的导入由人点「恢复」显式续跑。 + * 写不进去时(基准版本过期 stale_revision / 三方比的是旧的 L、import_stale_l)选好的格子一个不丢:前者重新读 + * 详情拿新版本,后者按现在的口径**重算三方**(refreshImport)再读回来,由人核对后再点一次——不拿旧 L 直接覆盖。 + * 这块只写业务说法,不出现取数语句、节点编号和字段路径。 + */ + const renderImports = (draft: CaliberDraft) => { + if (!draft.workflow_id) return null + const runs = importRuns ?? [] + const active = runs.find((run) => run.run_id === importId) ?? null + const metrics = (draft.metrics ?? []).filter((metric) => metric.id) + const nameOf = (id: string) => metrics.find((metric) => metric.id === id)?.name ?? I.unknownMetric + const baseline = validations?.field_baseline ?? draft.field_baseline + const coverage = baseline?.coverage + // 老工件没有 coverage 这一段:那时候 put_metrics 收的是整张卡,按 complete 处理(和 fieldbaseline.coverage_of 同一条规矩); + // 没有基线(baseline_unknown)时一律是读不出来,不能拿现在的内容当作它 + const coverageStatus = coverage?.status ?? (baseline?.status === 'known' ? 'complete' : 'unknown') + const missingFields = Object.values(coverage?.metrics ?? {}) + .reduce((total, row) => total + (row.missing?.length ?? 0), 0) + const uncoveredMetrics = coverage?.uncovered_metric_ids?.length ?? 0 + const coverageText = coverageStatus === 'complete' ? I.coverageComplete + : coverageStatus === 'partial' ? I.coveragePartial(missingFields, uncoveredMetrics) + : I.coverageUnknown + // 这一次要提交的格子:按**现在**的现状现算——格子还在、还没决定过、能接受、工作项没抽坏才收; + // 每条都带上工作项身份(item_id),同一个 metric_id 上有重复项时也不会指错 + const picking = active ? active.items.map((item) => ({ + item, + paths: item.fields.filter((cell) => importPicks[pickKey(item.item_id, cell.path)] === 'accept' + && cell.decided == null && cell.acceptable && itemAccepts(item)).map((cell) => cell.path), + rejects: item.fields.filter((cell) => importPicks[pickKey(item.item_id, cell.path)] === 'reject' + && cell.decided == null).map((cell) => cell.path), + })) : [] + const acceptItems = picking.filter((row) => row.paths.length) + .map((row) => ({ item_id: row.item.item_id, metric_id: row.item.metric_id, fields: row.paths })) + const rejectItems = picking.filter((row) => row.rejects.length).map((row) => ({ + item_id: row.item.item_id, fields: row.rejects, + ...(row.item.metric_id ? { metric_id: row.item.metric_id } : { seq: row.item.seq }), + })) + const acceptCount = acceptItems.reduce((total, item) => total + item.fields.length, 0) + const rejectCount = rejectItems.reduce((total, item) => total + item.fields.length, 0) + const resumable = active != null && (active.status === 'interrupted' || active.status === 'failed') + const busy = importBusy != null + return ( +
+
+

{I.title}

+ {I.hint} +
+

+ {I.coverageLabel}:{coverageText}。{I.coverageHint} +

+ +
+ + {I.createHint} +
+ {importsError != null &&
} + + {runs.length === 0 ? ( +

+ {I.runs}:{I.runsEmpty} +

+ ) : ( +
+

{I.runs}

+
    + {runs.map((run) => ( +
  • + +
  • + ))} +
+
+ )} + + {active && ( +
+
+ + {I.status[active.status] ?? active.status} + + {(active.status === 'queued' || active.status === 'running') && } + {I.itemsTotal(active.items_total)} + {active.conflicts.length > 0 && ( + + {I.conflicts(active.conflicts.length)} + + )} + {active.created_at && {I.createdAt(formatDateTime(active.created_at))}} +
+ {active.error && {active.error}} + {resumable && ( +
+ + {I.resumeHint} + + {I.unfinished(unfinishedItems(active))} + +
+ )} + + {active.items.length === 0 ? ( +

{I.noItems}

+ ) : ( +
    + {active.items.map((item) => { + const aligned = !!item.metric_id + const alignMode = String(item.align?.mode ?? '') + // 没对上要人指定;同名不同范围(身份对得上、引的原文不是同一段)也要人来定,所以 manual 一律开这个口 + const needsAlign = !aligned || alignMode === 'manual' + const clean = cleanPaths(item) + return ( +
  • +
    + {item.name || I.unknownMetric} + {aligned && · {nameOf(item.metric_id)}} + + {I.itemStatus[item.status] ?? I.state[item.status] ?? item.status} + +
    + + {needsAlign && ( +
    + {I.itemUnaligned} + + + {I.alignHint} +
    + )} + + {(alignMode === 'manual' || alignMode === 'new') && ( +

    + {I.reasonLabel}:{I.reason[alignMode] ?? alignMode} + {item.align?.reason ? ` · ${item.align.reason}` : ''} +

    + )} + {item.error &&

    {item.error}

    } + +
      + {item.fields.map((cell) => { + const choice = importPicks[pickKey(item.item_id, cell.path)] ?? '' + // 抽坏了的(failed)和没对齐上的一律不能接受;接受过的也不用再选 + const canAccept = itemAccepts(item) && cell.acceptable && cell.decided !== 'accepted' + const values: [string, string | null, string][] = [ + ['b', cellText(cell, 'b', draft.binding), I.b], + ['l', cellText(cell, 'l', draft.binding), I.l], + ['r', cellText(cell, 'r', draft.binding), I.r], + ] + return ( +
    • +
      + {fieldLabel(cell.path, draft.binding)} + + {I.state[cell.state] ?? cell.state} + + {cell.decided === 'accepted' && {I.accept}} + {cell.decided === 'rejected' && {I.reject}} + {cell.state === 'missing' && ( + + {I.missingNoDelete} + + )} +
      +
        + {values.map(([key, text, label]) => text != null && ( +
      • + {label}:{text} +
      • + ))} +
      +

      {I.stateHint[cell.state] ?? ''}

      + {cell.decided == null && ( +
      + + +
      + )} +
    • + ) + })} +
    + + {clean.length > 0 && ( +
    + {/* 一次收掉这条上无冲突的几格:把这几格**明确列出来**发(不发 auto),页面列了几格就只接受几格 */} + +
    + )} +
  • + ) + })} +
+ )} + + {active.items.length > 0 && ( +
+ + + {!acceptCount && !rejectCount && {I.nothingSelected}} + setImportNote(e.target.value)} /> +
+ )} + + {importStale && ( +
+ + {importStale.code === 'import_stale_l' + ? I.staleL(importStale.names) + : I.stale(importStale.current, importStale.base)} + +
+ )} + {importError != null &&
} + {(importAccepted || importRejected) && ( +
+ {importAccepted && ( + <> +

+ {I.accepted(importResult?.revision ?? null)} + {importResult?.replayed && · {I.replayed}} +

+

{I.acceptedHint}

+ + )} + {importRejected &&

{I.rejected}

} +
+ )} +
+ )} +
+ ) + } + + /** + * 用一句话改口径(K12):先调只读的提案接口,把 operations 翻成「哪条指标、哪一项写法、现在什么 → 保存后什么」, + * 不摆 JSON、节点编号和字段路径。含糊的业务条件先显示澄清项,一条操作都不产出——确认(confirm=true)之前, + * 服务端一个字节都不写;落版失败时这里的输入和预览原样留着。 + */ + const renderNl = (draft: CaliberDraft) => { + if (!draft.workflow_id) return null + const proposal = nlPreview + const changes = proposal?.ready ? nlChanges(draft, proposal.operations) : [] + const clarifications = proposal?.clarifications ?? [] + // 输入改过之后这份提案就不作数了:必须重新预览(确认的是预览时那一段原文,不是输入框里现在的字) + const touched = !!nlPreviewOf && nlText.trim() !== nlPreviewOf + const confirmable = !touched && proposal?.ready && changes.length > 0 && draft.revision != null + return ( +
+
+

{N.title}

+ {N.hint} +
+
+