口径起草一次到位:生成取数图并自动试运行,不再要求人工接一次运行

「不从指标定义编译 SQL」管的是事后比对的基准,不是起草。起草照样让模型写 SQL,但只允许
目录里的表和列、单条只读 SELECT、入口字段必须先声明;每条定义仍要能逐字对上原文。

起草成功即建工作流与 v1;试运行只跑取数与口径卡(derive.caliber_probe),不触发报告撰写,
也不会因为没有可用模型就判这份口径不行。接上一次运行保留为辅助入口。
This commit is contained in:
ThearchyHelios
2026-11-04 00:30:26 +08:00
parent 5a29bcd8a6
commit 13f1158191
6 changed files with 1298 additions and 165 deletions
+261 -30
View File
@@ -19,8 +19,10 @@
- GET /api/ledger/calibers、GET /api/ledger/calibers/{workflow_id}/{version}/{node_id}(router,搭建者):口径可调用描述
(app/ledger/descriptor.py):入口字段的 JSON Schema、依赖、能不能组合和出具;不返回 SQL 和参数值。
- POST /api/ledger/drafts/extract、GET /api/ledger/drafts、GET/PATCH /api/ledger/drafts/{id}、POST …/{id}/dismiss、
POST …/{id}/attach(router,搭建者):从业务文档起草口径(app/ledger/docdraft.py),草稿独立存在、不写进
workflows.graph;attach 才按一次真实运行补上取数路径(app/ledger/docattach.py)。
POST …/{id}/attach、GET …/{id}/trial(router,搭建者):从业务文档起草口径。主路径一次到位:模型读文档和数据目录,
产出定义 + 取数 SQL + 入口字段 + 指标表达式(app/ledger/draftplan.py),服务端校验收成草稿图、建草稿工作流和 v1,
后台自动只读试跑;草稿页给「定义 + 数 + 原文引用」。attach 保留为辅助入口:已经有跑对的答案时让它认这份定义
(app/ledger/docattach.py)。
这几个新接口都不放给访问密钥(auth/keys.KEY_ROUTES 不登记)。
"""
from __future__ import annotations
@@ -404,8 +406,142 @@ def _question_count(payload: dict[str, Any]) -> int:
def _status_for(payload: dict[str, Any]) -> str:
"""还有问题 → questions_open,否则 path_pending(等一次真实运行补取数路径)。"""
return "questions_open" if _question_count(payload) else "path_pending"
"""还有问题 → questions_open;没有问题且有图 → ready;没有图的老草稿 → path_pending。
questions_open 现在也有图和数,只是问题还没清完,不阻断试跑;path_pending 只留给这次改版之前起草、还没有取数路径的草稿。
"""
if _question_count(payload):
return "questions_open"
if payload.get("workflow_id") and payload.get("sql"):
return "ready"
return "path_pending"
#: 试跑最多等多久(秒)和轮询间隔:和 trial_caliber 的 300 × 0.1 一致
TRIAL_TIMEOUT_S = 30
TRIAL_POLL_S = 0.1
#: 运行到这里就是终态了(interrupted 归到 failed,接口契约只有三种状态)
TERMINAL_RUN_STATUSES = ("succeeded", "failed", "cancelled", "interrupted")
def _run_status(status: Any) -> str:
"""运行状态 → 接口契约里的 succeeded / failed / running。"""
if status == "succeeded":
return "succeeded"
if status in ("failed", "cancelled", "interrupted"):
return "failed"
return "running"
def _source_tables(source: DataSource) -> dict[str, Any]:
cache = source.schema_cache if isinstance(source.schema_cache, dict) else {}
tables = cache.get("tables")
return tables if isinstance(tables, dict) else {}
async def _schema_material(session: AsyncSession, source: DataSource) -> tuple[str, set[str]]:
"""这个数据源给模型看的表结构 + 数据目录文本,以及 SQL 允许出现的表名集合。
给模型的是「库概览 + 紧凑表名索引 + 前几十张表的字段/目录」(schema_view 的现成渲染),表名一律照目录原文,模型照着抄。
allowed_tables 收全部探查到的表(含 schema 前缀写法):文本里被截掉详情的表也允许,因为索引里有名字。
"""
from app.data import catalog, schema_view
cache = source.schema_cache if isinstance(source.schema_cache, dict) else {}
tables = _source_tables(source)
if not tables:
return "", set()
entries = await catalog.read_catalog(session, source.id)
notes = {table: entry.notes for table, entry in entries.items()}
lines = [schema_view.overview_line(source, catalog_tables=sum(
1 for entry in entries.values() if catalog.visible_notes(entry.notes)))]
lines.append(schema_view.table_index(source, notes))
for position, table in enumerate(tables):
if position >= 60:
break
lines.append(schema_view.table_detail(source, table, catalog_notes=notes))
schema = cache.get("schema")
allowed: set[str] = set()
for table in tables:
allowed.add(str(table))
if isinstance(schema, str) and schema:
allowed.add(f"{schema}.{table}")
return "\n\n".join(line for line in lines if line), allowed
async def _save_trial(draft_id: str, trial: dict[str, str]) -> None:
"""把试跑状态写进 draft.payload["trial"](用新会话:后台这一段和起草那段不是同一个事务)。"""
async with SessionLocal() as fresh:
row = await fresh.get(CaliberDraft, draft_id)
if row is None or not isinstance(row.payload, dict):
return
body = dict(row.payload)
body["trial"] = trial
row.payload = body
await fresh.commit()
async def _run_trial(*, draft_id: str, workflow_id: str, graph: dict[str, Any], values: dict[str, Any],
started_by: str | None) -> dict[str, str]:
"""后台试跑草稿的取数与口径卡,返回 payload["trial"] 的形状(run_id / status / error)。
跑的是**探针图**(取数 + 口径卡,`derive.caliber_probe`),不是整张草稿图:草稿图里带着报告撰写节点,
试跑只关心数对不对,不该为了一次试跑多花一次模型调用、也不该因为没有可用模型就判这份口径不行。
不复用 trial_caliber:那里要求「已发布」,草稿本来就没发布。来源记 caliber_trial;起来之后先写一次 run_id,
页面这时就能去看运行;轮询到终态或者等满 TRIAL_TIMEOUT_S,没跑完就照实答 running。
"""
from app.engine.runner import run_manager
from app.ledger.derive import NotDerivable, caliber_probe, load_pinned
card_id = next((n.get("id") for n in graph.get("nodes") or []
if isinstance(n, dict) and n.get("type") == "metrics"), None)
if not card_id:
return {"run_id": "", "status": "failed", "error": "这份草稿没有口径卡,没有可试运行的指标"}
try:
async with SessionLocal() as read:
pinned = await load_pinned(read, workflow_id, 1, str(card_id))
target = caliber_probe(pinned).graph
except NotDerivable as e:
return {"run_id": "", "status": "failed", "error": f"口径卡不能派生探针:{e.message}"}
try:
run = await run_manager.start(
graph=target, input_payload=values, run_class="exploratory", origin_kind="caliber_trial",
origin={"kind": "caliber_trial", "draft_id": draft_id, "workflow_id": workflow_id, "version": 1,
"node_id": str(card_id)},
started_by=started_by)
except Exception as e: # noqa: BLE001 - 试跑发起失败不该把已经生成的草稿弄没
logger.exception("草稿 %s 的试运行没有发起", draft_id)
return {"run_id": "", "status": "failed", "error": f"试运行没有发起:{e}"}
await _save_trial(draft_id, {"run_id": run.id, "status": "running", "error": ""})
row: Run | None = None
for _ in range(int(TRIAL_TIMEOUT_S / TRIAL_POLL_S)):
async with SessionLocal() as poll:
row = await poll.get(Run, run.id)
if row is None or row.status in TERMINAL_RUN_STATUSES:
break
await asyncio.sleep(TRIAL_POLL_S)
status = _run_status(row.status if row is not None else "running")
error = str(row.error or "") if row is not None and status == "failed" else ""
return {"run_id": run.id, "status": status, "error": error}
async def _trial_metrics(run_id: str) -> list[dict[str, Any]]:
"""试跑运行里口径卡上的指标值:复用证据接口读封存的现成函数,不另写指标集解析。"""
from app.api.evidence import _sealed, _sealed_cards
try:
sealed = await _sealed(run_id)
cards = {node_id: card for node_id, _, card in _sealed_cards(sealed)}
except Exception: # noqa: BLE001 - 证据读不出来就只给状态,不编造指标值
logger.exception("试跑 %s 的指标值读不出来", run_id)
return []
card = cards.get("card") or next(iter(cards.values()), None)
if not isinstance(card, dict):
return []
return [{k: m.get(k) for k in ("id", "name", "rendered", "value") if m.get(k) is not None}
for m in card.get("metrics") or [] if isinstance(m, dict) and m.get("id")]
def _draft_summary(draft: CaliberDraft) -> dict[str, Any]:
@@ -466,12 +602,15 @@ def _doc_title(docs: list[Document]) -> str:
async def _extract_in_background(draft_id: str) -> None:
"""后台起草:读文档的段落、调一次模型、和已发布口径对齐,结果写回这一行。
"""后台起草:读文档的段落和数据目录、调一次模型、校验收成草稿图、建草稿工作流、再跑一次试跑。
用新的会话:请求那一份在响应发出后就关了,后台接着用它写库是错的。失败写进 error、状态留在 drafting——
草稿不是「被驳回」,人改完文档还能再来一次。
用新的会话:请求那一份在响应发出后就关了,后台接着用它写库是错的。没有数据源或没有表结构时起草必须失败——SQL 只能
对照真实目录写,没有目录就不让模型猜。个别指标不合格只丢那一条、写进 dropped / open_questions;SQL 本身不合格才整份
失败(图跑不了,留着也没有意义)。
"""
from app.ledger import docdraft
from app.core.artifact_store import graph_hash
from app.db.models import WorkflowVersion
from app.ledger import docdraft, draftplan
async with SessionLocal() as session:
draft = await session.get(CaliberDraft, draft_id)
@@ -496,25 +635,69 @@ async def _extract_in_background(draft_id: str) -> None:
chunk_ids.append(chunk.id)
entries.append({"document_id": doc.id, "title": doc.title or doc.source or doc.id,
"chunk_ids": chunk_ids})
datasource = None
if draft.datasource_id:
source = await session.get(DataSource, draft.datasource_id)
if source is not None:
datasource = {"name": source.name, "type": source.kind, "description": source.description}
source = await session.get(DataSource, draft.datasource_id) if draft.datasource_id else None
if source is None:
draft.error = "没有数据源:生成取数 SQL 必须对照数据目录里的表和列"
draft.status = "failed"
await session.commit()
return
tables_text, allowed_tables = await _schema_material(session, source)
if not allowed_tables:
draft.error = "这个数据源还没有表结构:先探查表结构,再起草口径"
draft.status = "failed"
await session.commit()
return
datasource = {"name": source.name, "type": source.kind, "description": source.description}
guidance = str(origin.get("guidance") or "")
alignment: dict[str, list[Any]] = {"new": [], "duplicate": [], "conflict": []}
try:
result = await docdraft.extract(session, docs=entries, chunks=chunks,
guidance=str(origin.get("guidance") or ""), datasource=datasource)
result = await draftplan.plan(session, docs=entries, chunks=chunks, guidance=guidance,
datasource=datasource, tables_text=tables_text)
plan, problems = draftplan.normalize_plan(result, chunks, allowed_tables=allowed_tables)
base = {
"documents": entries, "metrics": plan["metrics"], "entry_fields": plan["entry_fields"],
"sql": plan["sql"], "version": 1,
"trial": {"run_id": "", "status": "running", "error": ""},
"dropped": problems, "truncated": result["truncated"], "model_id": result["model_id"],
}
if not plan["sql"] or not plan["metrics"]:
error = _problems_text(problems) or "模型没有给出可用的取数 SQL 和指标"
draft.payload = {**base, "trial": {"run_id": "", "status": "failed", "error": error}}
draft.model_id = result["model_id"] or None
draft.error = error
draft.status = "failed"
await session.commit()
return
# 对齐要扫所有已发布口径:某一份读不出来不该让整份草稿失败,照实不做对齐(alignment 三个空列表)
try:
existing = await _published_metrics(session)
except Exception: # noqa: BLE001 - 对齐是辅助信息,不是草稿本身
logger.exception("读已发布口径失败,草稿 %s 不做对齐", draft_id)
existing = []
alignment = docdraft.alignment(plan["metrics"], existing)
plan["datasource"] = source.name
graph = draftplan.build_graph(plan, name=draft.title,
question=guidance or draft.title)
questions = list(plan["open_questions"]) + [
f"{p['name']}:{p['reason']}" for p in problems
if p.get("name") not in ("sql", "metrics")]
workflow = Workflow(
name=(draft.title.strip() or "文档口径草稿")[:200],
description=(f"从业务文档起草的口径:{len(plan['metrics'])} 个指标,取数 SQL 由模型对照数据目录生成,"
f"后台自动只读试运行;人工审改后按受管级别发布"),
graph=graph, status="draft", tags=["doc_draft"],
origin={"kind": "doc_draft", "draft_id": draft.id, "datasource_id": source.id,
"documents": [doc.id for doc in docs], "guidance": guidance})
session.add(workflow)
await session.flush()
session.add(WorkflowVersion(workflow_id=workflow.id, version=1, graph=graph,
graph_hash=graph_hash(graph), note="从业务文档一次生成"))
payload = {
"documents": entries, "metrics": result["metrics"], "dropped": result["dropped"],
"open_questions": result["open_questions"],
"alignment": docdraft.alignment(result["metrics"], existing),
"truncated": result["truncated"], "model_id": result["model_id"],
**base, "workflow_id": workflow.id, "open_questions": questions,
"alignment": alignment,
}
except docdraft.DraftUnavailable as e:
draft.error = str(e) or "AI 起草不可用"
@@ -528,14 +711,31 @@ async def _extract_in_background(draft_id: str) -> None:
await session.commit()
return
draft.payload = payload
draft.workflow_id = workflow.id
draft.model_id = result["model_id"] or None
draft.error = None
draft.status = _status_for(payload)
await session.commit()
values = {field["name"]: field.get("default") for field in plan["entry_fields"]
if field.get("default") not in (None, "")}
try:
trial = await _run_trial(draft_id=draft_id, workflow_id=workflow.id, graph=graph, values=values,
started_by=draft.created_by)
except Exception as e: # noqa: BLE001 - 试运行出错也要写进 payload,不能让界面停在「试运行中」
logger.exception("草稿 %s 的试运行出错", draft_id)
trial = {"run_id": "", "status": "failed", "error": f"试运行出错:{e}"}
await _save_trial(draft_id, trial)
def _problems_text(problems: list[dict[str, Any]]) -> str:
"""把校验问题拼成一句给人看的原因(接口的 error 只有一个字段)。"""
return ";".join(f"{p.get('name') or '问题'}:{p.get('reason') or ''}".strip(":")
for p in problems if p.get("reason"))[:2000]
class DraftExtractIn(BaseModel):
"""从哪几份文档起草、起草时给模型看的附加要求。数据源只用来写清适用范围,不给表结构。"""
"""从哪几份文档起草、起草时给模型看的附加要求。数据源必须给:它的表结构和目录是 SQL 的唯一依据。"""
documents: list[str] = Field(min_length=1, max_length=20)
collection: str | None = Field(default=None, max_length=100)
@@ -546,23 +746,29 @@ class DraftExtractIn(BaseModel):
@router.post("/drafts/extract", status_code=201)
async def draft_extract(payload: DraftExtractIn, background: BackgroundTasks,
session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
"""从业务文档起草一份口径(app/ledger/docdraft.py):先建一行 drafting 立刻返回,模型在后台跑。
"""从业务文档起草一份口径(app/ledger/draftplan.py):先建一行 drafting 立刻返回,模型在后台跑。
文档必须都存在(缺的回 422,一个草稿都不建);数据源给了也必须存在。草稿只产出定义,不产出取数,也不写进
workflows.graph——path_pending 不是合法的图。抽取完的 payload / status 用 GET 看。"""
文档必须都存在(缺的回 422,一个草稿都不建);数据源必须给、必须存在,而且已经探查到表结构——SQL 只能对照真实目录
写,没有目录时让模型猜表,图跑不了。模型产出定义 + SQL + 入口字段后由服务端校验收成草稿图和 v1,后台自动只读试跑。
起草完的 payload / status / trial 用 GET 看。"""
from app.api.deps import current_principal, ensure_role
ensure_role("builder")
doc_ids = list(dict.fromkeys(str(d) for d in payload.documents if str(d).strip()))
if not doc_ids:
raise HTTPException(422, "至少要给一份文档")
if not payload.datasource_id:
raise HTTPException(422, "生成取数 SQL 需要数据源:请选一个已经探查过表结构的数据源")
found = {doc.id: doc for doc in (await session.execute(
select(Document).where(Document.id.in_(doc_ids)))).scalars()}
missing = [doc_id for doc_id in doc_ids if doc_id not in found]
if missing:
raise HTTPException(422, f"文档不存在,可能已被删除:{'、'.join(missing)}")
if payload.datasource_id and await session.get(DataSource, payload.datasource_id) is None:
source = await session.get(DataSource, payload.datasource_id)
if source is None:
raise HTTPException(422, "数据源不存在,可能已被删除")
if not _source_tables(source):
raise HTTPException(422, "这个数据源还没有表结构:先探查表结构,再起草口径")
docs = [found[doc_id] for doc_id in doc_ids]
draft = CaliberDraft(title=_doc_title(docs),
collection=payload.collection or (docs[0].collection or "default"),
@@ -576,8 +782,8 @@ async def draft_extract(payload: DraftExtractIn, background: BackgroundTasks,
@router.get("/drafts")
async def list_drafts(status: str | None = Query(default=None, description="按状态筛:drafting / questions_open / "
"path_pending / attached / rejected / failed"),
async def list_drafts(status: str | None = Query(default=None, description="按状态筛:drafting / ready / "
"questions_open / path_pending / attached / rejected / failed"),
session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
"""口径草稿列表,最近改过的在前。只给计数和状态,正文用 GET /api/ledger/drafts/{id} 看。"""
from app.api.deps import ensure_role
@@ -595,13 +801,38 @@ 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)、丢弃原因、未决问题、和已发布口径的对齐结果、关联工作流名。"""
"""一份草稿的完整内容:指标(含引用和 span)、取数 SQL、入口字段、试跑状态、丢弃原因、未决问题、和已发布口径的对齐
结果、关联工作流名。"""
from app.api.deps import ensure_role
ensure_role("builder")
return await _draft_view(session, await _draft_or_404(session, draft_id))
@router.get("/drafts/{draft_id}/trial")
async def get_draft_trial(draft_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
"""这份草稿的试跑:{run_id, status, metrics: [{id, name, rendered, value}], error}。
状态只有 succeeded / failed / running 三种;指标值读试跑运行封存的口径卡(和口径试跑同一个读法)。还没试跑(老草稿、
起草失败)回 404。只读,不发起运行。"""
from app.api.deps import ensure_role
ensure_role("builder")
draft = await _draft_or_404(session, draft_id)
payload = draft.payload if isinstance(draft.payload, dict) else {}
trial = payload.get("trial") if isinstance(payload.get("trial"), dict) else {}
run_id = trial.get("run_id")
if not isinstance(run_id, str) or not run_id:
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": [],
"error": str(trial.get("error") or "")}
status = _run_status(run.status)
metrics = await _trial_metrics(run.id) if status == "succeeded" else []
return {"run_id": run.id, "status": status, "metrics": metrics, "error": str(run.error or "")}
def _check_metrics(metrics: Any) -> list[dict[str, Any]]:
"""PATCH 换指标时只做结构校验(不重跑引用核对:引用是模型交的,人改过的段落没法再逐字对一遍)。"""
if not isinstance(metrics, list):
@@ -633,8 +864,8 @@ class DraftPatchIn(BaseModel):
async def patch_draft(draft_id: str, payload: DraftPatchIn, session: AsyncSession = Depends(get_session)
) -> dict[str, Any]:
"""改一份草稿:metrics 整体替换(只做结构校验,不重跑引用核对);resolved 里的问题从跨指标和各指标的问题里删掉。
据此重算状态(还有问题 → questions_open,否则 path_pending)。已经 attach 或驳回的草稿不改状态——那时它说的
已经不是一份草稿了。"""
据此重算状态(还有问题 → questions_open,否则有图 → ready、没有图的老草稿 → path_pending)。已经 attach 或驳回的
草稿不改状态——那时它说的已经不是一份草稿了。"""
from app.api.deps import ensure_role
ensure_role("builder")
@@ -663,7 +894,7 @@ async def patch_draft(draft_id: str, payload: DraftPatchIn, session: AsyncSessio
metrics = payload_data.get("metrics")
# 起草失败的草稿补上真指标后要能往前走;没有指标时不重算,免得空草稿被当成「待接数据路径」
if isinstance(metrics, list) and metrics and draft.status in ("drafting", "questions_open",
"path_pending", "failed"):
"path_pending", "ready", "failed"):
draft.status = _status_for(payload_data)
await session.commit()
return await _draft_view(session, draft)
+7 -7
View File
@@ -1094,12 +1094,12 @@ class WebhookDelivery(Base):
class CaliberDraft(Base, TimestampMixin):
"""从业务文档起草的一份口径(app/ledger/docdraft.py 的产出)。
"""从业务文档起草的一份口径(app/ledger/draftplan.py 的产出)。
草稿在 path_pending 下没有取数路径,不是合法图(validate_graph 会挡),所以不写进 workflows.graph:另存一行,
等 attach(app/ledger/docattach.py)按一次真实运行补上取数路径、人审过再进版本。payload 的形状见
docdraft.extract 的返回(documents / metrics / dropped / open_questions / alignment / truncated / model_id),
origin 记这一份草稿从哪些文档、用哪句话问出来的,attach 之后工作流 id 记在 workflow_id 上。
主路径一次到位:模型读文档和数据目录,产出定义 + 取数 SQL + 入口字段 + 指标表达式;服务端校验收成草稿图,建一个
status="draft" 的工作流和 v1,后台自动只读试跑。payload 的形状见接口契约(documents / metrics / entry_fields / sql /
workflow_id / version / trial / open_questions / alignment / dropped / truncated / model_id),这张草稿对应的工作流 id
记在 workflow_id 上。attach(app/ledger/docattach.py)保留为辅助入口:已经有跑对的答案时让它认这份定义。
"""
__tablename__ = "caliber_drafts"
@@ -1107,11 +1107,11 @@ class CaliberDraft(Base, TimestampMixin):
id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
title: Mapped[str] = mapped_column(String(200), default="")
collection: Mapped[str] = mapped_column(String(100), default="default")
# 起草时给模型看的数据源(只给名字和类型,用来写清适用范围);源删了草稿照旧在,只丢这一条线索
# 起草时给模型看的数据源:表结构和数据目录是取数 SQL 的唯一依据;源删了草稿照旧在,只丢这一条线索
datasource_id: Mapped[str | None] = mapped_column(
ForeignKey("data_sources.id", ondelete="SET NULL"), default=None
)
# 同 docdraft.STATUSES:drafting | questions_open | path_pending | attached | rejected
# 同 docdraft.STATUSES:drafting | ready | questions_open | path_pending | attached | rejected | failed
status: Mapped[str] = mapped_column(String(20), default="drafting", index=True)
payload: Mapped[dict[str, Any]] = mapped_column(default=dict)
# 这份草稿从哪来:{"documents": [文档 id], "guidance": 用户补充要求}
+12 -10
View File
@@ -1,12 +1,12 @@
"""业务文档 → 口径草稿:只产出定义,不产出取数(docs/design/next-round/02-口径账本.md 做法 8 的文档一侧)。
"""业务文档 → 口径草稿的定义抽取,以及草稿共用的引用核对、对齐和合并(docs/design/next-round/02-口径账本.md 做法 8 的文档一侧)。
**为什么草稿只到定义为止。** 文档里写的是业务说法(名称、同义词、粒度、时间字段、过滤、分子分母、维度),不是库里的
表、列和 SQL。取数必须来自一次真实运行:运行里执行过什么、结果对不对,只有运行本身能证明。所以这个模块的产出固定为
定义卡需要的那几项,模型回复里一旦出现 SQL / 表名 / 列名字段,整条指标丢弃,不带着它往下走。
**这条抽取路径只产出定义。** 主路径(定义 + 取数 SQL 一次到位)在 ledger/draftplan.py:那边读数据目录、由模型写 SQL、
服务端建图并试跑。这里的 extract 仍然只抽定义,留给「已经有跑对的答案,让它认这份定义」的辅助路径(docattach);引用核对、
对齐、合并定义这些规则两边共用,所以留在这个模块。
**为什么草稿不写成图。** path_pending 的草稿还没有取数路径,不是合法图(validate_graph 会挡),写进 workflows.graph
只会让工作流列表和画布读到一个跑不了的版本。草稿先独立存在,等取数路径有了、人审过了再进版本。这个模块因此不碰
数据库:纯逻辑 + 一次模型调用,调用方拿到结果自己决定存哪里。
**为什么这个模块不写成图。** 它只负责把原文里的业务说法抽成定义卡需要的那几项:不碰取数、不碰数据库,纯逻辑加一次模型
调用,调用方拿到结果自己决定存哪里。建图(取数 SQL → start / fetch / card / write / out)在 draftplan.build_graph,
docattach 接上运行的那一路用的是 certify.build_graph。
**为什么引用要逐字核对。** 「文档里说过」是这份草稿唯一的事实来源。模型转述得再像,也要能在原文里按归一化空白
(换行、制表、全角空格)定位到那一句;定位不到就不算引用。span 是原文下标,界面据此高亮,也是之后复核的依据。
@@ -21,9 +21,11 @@ import re
from collections.abc import Iterable, Mapping
from typing import Any
#: 草稿的状态。path_pending 不是合法图,attached 之后取数路径才来自一次真实运行。
#: failed 是起草这一步没跑成(没有可用模型、模型回复读不懂),和 rejected(人判它不是口径)不是一回事。
STATUSES = ("drafting", "questions_open", "path_pending", "attached", "rejected", "failed")
#: 草稿的状态。ready 是主路径的常态:图已生成(含取数 SQL)、没有未决问题、可试跑可签字发布;questions_open 有图也有数,
#: 只是问题还没清完(不阻断试跑);path_pending 只留给这次改版之前起草、还没有取数路径的老草稿;attached 是经辅助入口接上
#: 一次真实运行之后的。failed 是起草这一步没跑成(没有可用模型、模型回复读不懂、SQL 不合格),和 rejected(人判它不是口径)
#: 不是一回事。
STATUSES = ("drafting", "ready", "questions_open", "path_pending", "attached", "rejected", "failed")
#: 一次发给模型的总字数上限(按 chunk 边界截断,见 extract)
MAX_INPUT_CHARS = 40000
+450
View File
@@ -0,0 +1,450 @@
"""业务文档 + 数据目录 → 一份一次到位的口径草稿:定义、取数 SQL、入口字段、指标表达式(docs/design 做法 8 的主路径)。
**为什么这次要模型写 SQL。** 文档里只有业务说法,没有表名。但只抽定义,人还得自己去问一次数、再把运行 id 接回来,等于把
「口径怎么写」拆成两段,谁都说不清草稿什么时候算数。主路径改成一次产出可试跑的图:模型读文档、对照数据目录写一条只读
SELECT,服务端把 SQL、入口字段、口径卡、报告串成图,后台跑一次,草稿页直接给「定义 + 数 + 原文引用」。
**为什么目录是唯一依据。** 文档里没有表名列名,模型只能从调用方给的目录里挑。所以没有数据源、或数据源还没探查表结构时,
调用方必须拒收(api/ledger 的 422):让模型凭空猜表,猜出来的图跑不了,还不如不做。normalize_plan 再核对一遍 SQL 里出现的
表都在目录里,防止模型从示例、同义词里编出表名。
**为什么 SQL 只收单条只读 SELECT。** 草稿会在后台自动跑一次。多语句、DML/DDL、注释后藏的第二条都可能在试跑时改库;
这里按 sqlglot 解析后的语句数判定,不靠字符串里有没有分号(字符串字面量里的分号不算)。注释里的第二条照样会被解析成
第二条语句,所以也拒。
**为什么表达式必须是 cell(nodes.fetch, 0, '列名')。** 试跑和之后按口径出具都从口径卡读值。取数节点固定叫 fetch(见
build_graph),单行结果取第 0 行的某一列;写成别的样子,卡上就没有值,图能建但出不了数。
**为什么引用核对还是照 docdraft 的老规矩。** 定义的事实来源还是文档原文。模型转述得再像,也要能在原文里逐字定位;一条
引用都核不上的指标整条丢弃,写进 problems 交给人看。这里只做校验,不改 docdraft 的规则。
**为什么不落库、不导 app.api。** 这个模块是纯逻辑加一次模型调用:从哪读文档、允许哪些表、结果存成什么,都由调用方决定。
测试注入假模型,不会发真实请求。
"""
from __future__ import annotations
import re
from collections.abc import Mapping
from typing import Any
from app.ledger import docdraft
#: 一次发给模型的材料上限(按 chunk 边界截断;表目录先截到这个数以内)
MAX_INPUT_CHARS = docdraft.MAX_INPUT_CHARS
MAX_TABLES_CHARS = 24000
#: 取数 SQL 的长度上限(字符)。再长的查询不是草稿该承载的
MAX_SQL_CHARS = 20000
#: 入口字段能写的类型(apps/spec.FORM_TYPES 的子集;日期用 string + description 说清)
ENTRY_TYPES = ("string", "number", "integer", "boolean")
#: 指标里固定出现的字段(顺序照接口契约)
METRIC_FIELDS = ("id", "name", "synonyms", "unit", "decimals", "expression", "definition", "open_questions")
#: SQL 模板里的入口占位符:{{ input.x }}(引号内外都认)
_INPUT = re.compile(r"\{\{\s*input\.([A-Za-z_][\w-]*)\s*\}\}")
#: 口径卡的取值表达式,列名可以用单引号或双引号
_EXPRESSION = re.compile(r"^cell\(\s*nodes\.fetch\s*,\s*0\s*,\s*['\"]([^'\"]+)['\"]\s*\)$")
#: 只读查询的根节点:普通 SELECT,或各分支都是 SELECT 的 UNION
_WRITE_NODES = ("Insert", "Update", "Delete", "Create", "Drop", "Alter", "Merge", "TruncateTable", "Command")
_SYSTEM = """你是业务口径与取数模板的起草助手。读给定的业务文档和数据目录,一次产出一份可试跑的口径。
硬性约束:
1. 只输出一个 JSON 对象,不要写解释,不要写 Markdown 代码块之外的话。
2. sql 是取数模板,只能是**一条只读 SELECT**:不要多语句、不要 INSERT/UPDATE/DELETE/DDL,也不要在注释后面再藏一条。
表和列只能来自「数据目录」,表名、列名照抄,不许猜、不许编。
3. sql 里需要按入口筛选时写 '{{ input.字段名 }}'(字符串)或 {{ input.字段名 }}(数),并在 entry_fields 里声明同名
字段;不要把日期、门店之类的字面量写死。
4. 每条指标都要有 expression,固定写成 cell(nodes.fetch, 0, '列名'),列名是 sql 最外层 SELECT 的输出列名。
5. 每条指标的定义必须带 citations:引用逐字抄原文,chunk 写材料里方括号内的 id。核对不上、或原文里没有依据的定义
不要写进指标,写进 open_questions。
6. 拿不准的不要猜,写进 open_questions,用一句问得清的话。不要编造文档里没有的数字、单位、生效日期。
输出格式:
{
"entry_fields": [
{"name": "start", "type": "string", "required": true, "default": "", "description": "开始日期,格式 YYYY-MM-DD"}
],
"sql": "SELECT SUM(amount) AS gmv FROM orders WHERE paid_at >= '{{ input.start }}'",
"metrics": [
{
"id": "m1",
"name": "指标名称",
"synonyms": ["同义词"],
"unit": "单位(文档没写就留空)",
"decimals": 2,
"expression": "cell(nodes.fetch, 0, 'gmv')",
"definition": {
"text": "口径说明",
"scope": "适用范围",
"exclusions": ["不包含的情况"],
"owner": "文档写明的负责人或部门",
"effective_from": "生效日期(文档原文写法)",
"citations": [{"chunk": "c1", "quote": "逐字原文"}]
},
"open_questions": ["还没说清、需要业务确认的问题"]
}
],
"open_questions": ["跨指标、以及整条 SQL 还没把握的问题"]
}
"""
def _collapse(text: str) -> str:
return re.sub(r"\s+", " ", text).strip()
def _order(chunks: Mapping[str, dict]) -> list[str]:
def key(chunk_id: str) -> tuple[int, str]:
chunk = chunks[chunk_id] if isinstance(chunks[chunk_id], Mapping) else {}
ordinal = chunk.get("ordinal")
return (ordinal if isinstance(ordinal, int) else 0, chunk_id)
return sorted(chunks, key=key)
def _doc_line(doc: Any) -> str:
if not isinstance(doc, Mapping):
return str(doc)
doc_id = doc.get("document_id") or doc.get("id") or ""
title = doc.get("title") or doc.get("filename") or doc.get("name") or doc_id
return f"- {doc_id}:{title}"
def _chunk_block(chunk_id: str, chunk: Any) -> str:
chunk = chunk if isinstance(chunk, Mapping) else {}
ordinal = chunk.get("ordinal")
where = f" · 第 {ordinal} 段" if isinstance(ordinal, int) else ""
document = chunk.get("document_id") or ""
return f"[{chunk_id}](文档 {document}{where})\n{chunk.get('content') or ''}"
def _human(docs: list[dict], chunks: Mapping[str, dict], guidance: str, datasource: dict | None,
tables_text: str) -> str:
parts = ["文档清单:", *(_doc_line(doc) for doc in docs), "",
"逐段原文(引用时 chunk 写方括号里的 id,quote 逐字抄):"]
parts.extend(_chunk_block(chunk_id, chunks[chunk_id]) for chunk_id in _order(chunks))
parts.append("")
if datasource:
bits = [str(datasource.get(key)) for key in ("name", "type", "dialect", "description")
if datasource.get(key)]
parts.append("数据源:{}".format(" · ".join(bits)))
parts.append("数据目录(sql 只能用这里的表和列,表名列名照抄):")
parts.append(tables_text.strip() or "(没有给出表结构,不能写 sql)")
parts.append("")
parts.append("用户补充要求:{}".format(guidance.strip() if guidance and guidance.strip() else "(无)"))
return "\n".join(parts)
def prompt(docs: list[dict], chunks: dict[str, dict], guidance: str = "", datasource: dict | None = None,
tables_text: str = "") -> list[Any]:
"""构造 system + human:文档原文 + 数据目录。目录是 sql 的唯一依据,和原文一样原样交给模型。"""
from langchain_core.messages import HumanMessage, SystemMessage
return [SystemMessage(content=_SYSTEM),
HumanMessage(content=_human(docs, chunks, guidance, datasource, tables_text))]
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) -> tuple[dict[str, dict], str, bool]:
"""把材料压到 MAX_INPUT_CHARS 以内:先截表目录尾部,再从后往前按 chunk 边界丢,最后截仅剩的那一段。
表目录先截:SQL 必须写在目录里的表上,目录比文档的细枝末节更硬;被截掉的是表详情,表名索引还在最前面。
"""
kept = dict(chunks)
tables = tables_text
truncated = False
if len(tables) > MAX_TABLES_CHARS:
tables = tables[:MAX_TABLES_CHARS]
truncated = True
def size() -> int:
return _chars(prompt(docs, kept, guidance, datasource, tables))
order = _order(kept)
while size() > MAX_INPUT_CHARS and len(order) > 1:
kept.pop(order.pop())
truncated = True
if size() > MAX_INPUT_CHARS and order:
chunk_id = order[0]
chunk = dict(kept[chunk_id]) if isinstance(kept[chunk_id], Mapping) else {}
content = str(chunk.get("content") or "")
excess = size() - MAX_INPUT_CHARS
chunk["content"] = content[:max(0, len(content) - excess)]
kept[chunk_id] = chunk
truncated = True
if size() > MAX_INPUT_CHARS:
excess = size() - MAX_INPUT_CHARS
tables = tables[:max(0, len(tables) - excess)]
truncated = True
return kept, tables, truncated
async def plan(session: Any, *, docs: list[dict], chunks: dict[str, dict], guidance: str = "",
datasource: dict | None = None, tables_text: str = "", model: Any = None) -> dict:
"""一次模型调用,返回 {entry_fields, sql, metrics, open_questions, model_id, truncated}(未校验)。
不落库。model 可注入(测试用假对象:有 async ainvoke(messages),回复有 .content);不给就按设置解析,模型不可用时抛
docdraft.DraftUnavailable。SQL 的对错、引用能不能核对,交给 normalize_plan。
"""
from app.engine.state import message_text
if model is None:
from app.data.recipe_ai import resolve_draft_model
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 起草不可用")
else:
named = getattr(model, "model_name", None) or getattr(model, "model", None)
model_id = named if isinstance(named, str) else ""
kept, tables, truncated = _fit(docs, chunks, guidance, datasource, tables_text)
reply = await model.ainvoke(prompt(docs, kept, guidance, datasource, tables))
data = docdraft.parse_reply(message_text(reply))
metrics = data.get("metrics")
questions = data.get("open_questions")
return {
"entry_fields": data.get("entry_fields") if isinstance(data.get("entry_fields"), list) else [],
"sql": data.get("sql") if isinstance(data.get("sql"), str) else "",
"metrics": metrics if isinstance(metrics, list) else [],
"open_questions": [q for q in questions if isinstance(q, str) and q.strip()]
if isinstance(questions, list) else [],
"model_id": model_id,
"truncated": truncated,
}
# ==========================================================================
# 校验
# ==========================================================================
def _entry_fields(value: Any, problems: list[dict]) -> list[dict]:
"""入口字段归一化:名字必填、不重名;类型落回能认的几种,认不出的按文字。"""
out: list[dict] = []
seen: set[str] = set()
for position, item in enumerate(value if isinstance(value, list) else [], start=1):
if not isinstance(item, Mapping):
problems.append({"name": f"第 {position} 个入口字段", "reason": "不是一个对象"})
continue
name = item.get("name")
if not isinstance(name, str) or not name.strip():
problems.append({"name": f"第 {position} 个入口字段", "reason": "缺少字段名"})
continue
name = name.strip()
if name in seen:
problems.append({"name": name, "reason": "入口字段重名"})
continue
seen.add(name)
kind = item.get("type")
if kind not in ENTRY_TYPES:
kind = "string"
default = item.get("default")
if not isinstance(default, (str, int, float, bool)):
default = None
description = item.get("description")
out.append({"name": name, "type": kind, "required": bool(item.get("required")),
"default": default,
"description": description.strip() if isinstance(description, str) else ""})
return out
def _sql_problem(sql: str, allowed_tables: set[str]) -> str | None:
"""单条只读 SELECT、表都在目录里;不满足时返回一句给人看的原因。"""
if len(sql) > MAX_SQL_CHARS:
return f"SQL 超过 {MAX_SQL_CHARS} 字,草稿不承载这么长的查询"
body = _INPUT.sub("?", sql)
try:
import sqlglot
from sqlglot import exp
except ImportError: # pragma: no cover - sqlglot 是现有依赖,装不上时照实拒
return "没有 SQL 解析器,不能校验这条查询"
try:
statements = [item for item in sqlglot.parse(body) if item is not None]
except Exception as e: # noqa: BLE001 - 语法错、方言特性:都按解析不了
return f"SQL 解析不了:{e}"
if len(statements) != 1:
return "只能是一条语句:多语句、或注释后藏着第二条语句的,一律不收"
tree = statements[0]
if not isinstance(tree, (exp.Select, exp.Union)):
return "只能是只读 SELECT"
if isinstance(tree, exp.Union) and not all(isinstance(part, exp.Select) for part in tree.find_all(exp.Select)):
return "只能是只读 SELECT"
if any(tree.find(getattr(exp, name)) is not None for name in _WRITE_NODES):
return "只能是只读 SELECT,不能有写操作或建表、删表这类语句"
if isinstance(tree, exp.Select) and tree.args.get("into"):
return "只能是只读 SELECT,不能把结果写进另一张表"
cte_names = {str(cte.alias or "").casefold() for cte in tree.find_all(exp.CTE)}
allowed = {str(name).casefold() for name in allowed_tables}
used: list[str] = []
for table in tree.find_all(exp.Table):
name = str(table.name or "")
short = name.rsplit(".", 1)[-1]
if not name or name.casefold() in cte_names or short.casefold() in cte_names:
continue
db = str(table.db or "")
keys = {name.casefold(), short.casefold()}
if db:
keys.add(f"{db}.{name}".casefold())
if not (keys & allowed):
used.append(name)
if used:
return f"SQL 用了数据目录里没有的表:{'、'.join(dict.fromkeys(used))}"
if not any(True for table in tree.find_all(exp.Table)
if str(table.name or "").casefold() not in cte_names):
return "SQL 没有引用任何表:请对照数据目录写取数"
return None
def _metric(item: Mapping, position: int, problems: list[dict]) -> dict | None:
"""一条已经过 docdraft 引用核对的指标:再查 expression,归一成契约里的字段。"""
name = str(item.get("name") or "").strip()
expression = item.get("expression")
if not isinstance(expression, str) or not _EXPRESSION.match(expression.strip()):
problems.append({"name": name or f"第 {position} 条",
"reason": "expression 必须是 cell(nodes.fetch, 0, '列名'),列名用 sql 的输出列名"})
return None
definition = item.get("definition") if isinstance(item.get("definition"), Mapping) else {}
citations = definition.get("citations") if isinstance(definition.get("citations"), list) else []
decimals = item.get("decimals")
if isinstance(decimals, bool) or not isinstance(decimals, int):
decimals = None
synonyms = item.get("synonyms")
questions = item.get("open_questions")
return {
"id": str(item.get("id") or "").strip(),
"name": name,
"synonyms": [s.strip() for s in synonyms if isinstance(s, str) and s.strip()]
if isinstance(synonyms, list) else [],
"unit": item.get("unit") if isinstance(item.get("unit"), str) else "",
"decimals": decimals,
"expression": expression.strip(),
"definition": {
"text": definition.get("text") if isinstance(definition.get("text"), str) else "",
"scope": definition.get("scope") if isinstance(definition.get("scope"), str) else "",
"exclusions": [str(v) for v in definition.get("exclusions") or [] if isinstance(v, str)]
if isinstance(definition.get("exclusions"), list) else [],
"owner": definition.get("owner") if isinstance(definition.get("owner"), str) else "",
"effective_from": definition.get("effective_from")
if isinstance(definition.get("effective_from"), str) else "",
"citations": citations,
},
"open_questions": [q for q in questions if isinstance(q, str) and q.strip()]
if isinstance(questions, list) else [],
}
def normalize_plan(raw: Any, chunks: Mapping[str, dict], *, allowed_tables: set[str]) -> tuple[dict, list[dict]]:
"""校验模型交回的草案。返回 (可落库的 plan, problems)。
problems 的形状是 {"name": …, "reason": …},name 能认出是哪一条就用名字,认不出按序号说。硬规则:SQL 单条只读、表都在
目录里;每条指标的 expression 是 cell(nodes.fetch, 0, '列名');至少一条引用能在原文里逐字核对上(复用
docdraft.normalize_metrics 的核对)。个别指标不合格只丢那一条,problems 里写清为什么;SQL 不合格时 plan["sql"] 为空,
由调用方决定整份草稿算失败。
"""
body = raw if isinstance(raw, Mapping) else {}
problems: list[dict] = []
entry_fields = _entry_fields(body.get("entry_fields"), problems)
sql = body.get("sql")
sql_text = sql.strip() if isinstance(sql, str) else ""
if not sql_text:
problems.append({"name": "sql", "reason": "没有给出取数 SQL"})
else:
reason = _sql_problem(sql_text, allowed_tables)
if reason:
problems.append({"name": "sql", "reason": reason})
sql_text = ""
else:
declared = {field["name"] for field in entry_fields}
missing = sorted(set(_INPUT.findall(sql_text)) - declared)
if missing:
problems.append({"name": "sql",
"reason": f"SQL 用了没有声明的入口字段:{'、'.join(missing)}"})
sql_text = ""
checked, dropped = docdraft.normalize_metrics(body.get("metrics"), dict(chunks))
problems.extend(dropped)
metrics: list[dict] = []
seen_ids: set[str] = set()
for position, item in enumerate(checked, start=1):
metric = _metric(item, position, problems)
if metric is None:
continue
if not metric["id"] or metric["id"] in seen_ids:
metric["id"] = f"m{len(metrics) + 1}"
while metric["id"] in seen_ids:
metric["id"] += "_"
seen_ids.add(metric["id"])
metrics.append(metric)
if not metrics:
problems.append({"name": "metrics", "reason": "没有一条指标通过校验"})
questions = body.get("open_questions")
plan_out = {
"entry_fields": entry_fields,
"sql": sql_text,
"metrics": metrics,
"open_questions": [q.strip() for q in questions if isinstance(q, str) and q.strip()]
if isinstance(questions, list) else [],
}
return plan_out, problems
# ==========================================================================
# 建图(确定性,和 certify.build_graph 同一个形状)
# ==========================================================================
def build_graph(plan: dict, *, name: str, question: str = "") -> dict:
"""草案 → 草稿图:start(input) → fetch(tool) → card(metrics) → write(report) → out(output),过 auto_layout。
plan["datasource"] 是取数节点指向的数据源名(调用方按这次的数据源补,不采信模型回复里的名字)。调用两次结果逐字一致:
节点 id、坐标都由输入决定,没有时间戳。报告配置、出口契约照 certify.build_graph 的写法,发布门禁认的就是这一套
(REPORT_POLICY、metrics_from、required)。
"""
from app.engine.governance import REPORT_POLICY
from app.engine.layout import auto_layout
from app.engine.schema import GraphSpec
from app.ledger.certify import REPORT_INSTRUCTIONS, REPORT_INSTRUCTIONS_PARAMS
from app.tools.datasource import QUERY_PREFIX
fields = [dict(f) for f in plan.get("entry_fields") or []]
metrics = [dict(m) for m in plan.get("metrics") or []]
source = str(plan.get("datasource") or "")
report_cfg: dict[str, Any] = {}
if fields:
report_cfg["instructions"] = REPORT_INSTRUCTIONS_PARAMS.format(
params=",".join(f"{f['name']} = {{{{ input.{f['name']} }}}}" for f in fields))
else:
report_cfg["instructions"] = REPORT_INSTRUCTIONS.format(question=question or name or "(问题)")
report_cfg.update({key: value for key, value, _ in REPORT_POLICY})
report_cfg["metrics_from"] = ["card"]
contract: dict[str, Any] = {"report_from": "write", "metrics_from": "card",
"required": [m["id"] for m in metrics]}
chain = [
{"id": "start", "type": "input", "position": {"x": 0, "y": 0},
"data": {"label": "入口", "config": {"fields": fields}}},
{"id": "fetch", "type": "tool", "position": {"x": 0, "y": 0},
"data": {"label": "取数", "config": {"tool": f"{QUERY_PREFIX}{source}",
"args": {"sql": str(plan.get("sql") or "")}}}},
{"id": "card", "type": "metrics", "position": {"x": 0, "y": 0},
"data": {"label": "口径卡", "config": {"caliber": (name.strip() or question or "口径")[:40],
"caliber_version": "v1", "metrics": metrics}}},
{"id": "write", "type": "report", "position": {"x": 0, "y": 0},
"data": {"label": "报告", "config": report_cfg}},
{"id": "out", "type": "output", "position": {"x": 0, "y": 0},
"data": {"label": "出口", "config": {"fields": [{"name": "报告", "value": "{{ nodes.write.text }}"}],
"contract": contract}}},
]
edges = [{"source": a["id"], "target": b["id"]} for a, b in zip(chain, chain[1:])]
return auto_layout(GraphSpec.model_validate({"nodes": chain, "edges": edges})).model_dump(mode="json")
__all__ = ["ENTRY_TYPES", "MAX_INPUT_CHARS", "MAX_SQL_CHARS", "MAX_TABLES_CHARS", "METRIC_FIELDS",
"build_graph", "normalize_plan", "plan", "prompt"]
+368 -118
View File
@@ -1,47 +1,87 @@
"""从业务文档起草口径(app/ledger/docdraft.py,/api/ledger/drafts…):草稿独立于工作流存在。
"""从业务文档起草口径(app/ledger/draftplan.py + /api/ledger/drafts…):一次产出定义、SQL、入口和图。
- 抽取先建一行 drafting、在后台跑模型,结果写回 payload;缺文档 422、一个草稿都不建;
- 草稿只产出定义:payload 里是 metrics / dropped / open_questions / alignment,没有 SQL;
- PATCH 整体换指标、消掉已答清的问题并重算状态;dismiss 置 rejected 并写审计;列表给计数、按改过的先后排。
- 抽取先建一行 drafting、在后台跑模型;结果写成草稿:payload 里有 metrics / sql / entry_fields / trial,工作流和 v1 已建;
- 没有数据源、或数据源没有表结构时 422,一个草稿都不建;SQL 对照不上目录时草稿 failed;
- 有未决问题 → questions_open(图和试跑照样有),没有 → ready;
- PATCH 换指标 / 消问题并重算状态;dismiss 置 rejected 并写审计;列表给计数、按改过的先后排;
- GET /drafts/{id}/trial 交回契约里的形状。
模型一律 monkeypatch 掉(docdraft.extract 换成一个固定结果),测试不发真实请求。
模型一律注入假模型(monkeypatch resolve_draft_model),试跑也换成假的(不启动引擎),测试不发真实请求。
"""
from __future__ import annotations
import copy
import json
import sys
import types
import uuid
import pytest
from httpx import ASGITransport, AsyncClient
from sqlalchemy import delete, select
from app.api import ledger as api_ledger
from app.data import recipe_ai
from app.db.base import SessionLocal
from app.db.models import AuditEvent, CaliberDraft, Chunk, Document, Workflow
from app.ledger import docdraft
from app.db.models import (AuditEvent, CaliberDraft, Chunk, DataSource, Document, Run, Workflow,
WorkflowVersion)
from app.engine.schema import GraphSpec, validate_graph
from app.main import app
METRIC = {
"name": "已支付退款率",
"synonyms": ["退款率"],
"unit": "%",
"grain": "日",
"time_field": "支付时间",
"filters": ["只算已支付"],
"numerator": "已支付后退款的订单数",
"denominator": "已支付订单数",
"dimensions": ["门店"],
"definition": {"text": "已支付订单里发生退款的比例", "scope": "全部门店", "exclusions": [], "owner": "运营",
"effective_from": "2026-01-01",
"citations": [{"chunk": "c1", "document_id": "d1", "span": [0, 2], "quote": "退款率"}]},
"open_questions": ["退款算不算已支付当天的"],
}
#: 真实的试跑实现:autouse 的 fake_trial 会把它换掉,这一个用例换回来跑真引擎
REAL_RUN_TRIAL = api_ledger._run_trial
#: 文档原文:两段,退款率的事实来源
CHUNK_ONE = "退款率 = 已支付后退款的订单数 / 已支付订单数"
CHUNK_TWO = "退款率按门店拆,只算已支付的订单"
def result(metrics=None, questions=None, model_id="fake-model"):
return {"metrics": copy.deepcopy(metrics if metrics is not None else [METRIC]),
"dropped": [{"name": "第 2 条", "reason": "没有一条引用能在原文里逐字核对上"}],
"open_questions": list(questions or []), "truncated": False, "model_id": model_id}
def plan_reply(chunk_id: str, *, questions=None, sql: str | None = None, metrics=None) -> str:
"""模型回复:一条指标,引用逐字抄原文。"""
metric = {
"id": "m1", "name": "已支付退款率", "synonyms": ["退款率"], "unit": "%", "decimals": 2,
"expression": "cell(nodes.fetch, 0, 'refund_rate')",
"definition": {"text": "已支付订单里发生退款的比例", "scope": "全部门店", "exclusions": [],
"owner": "运营", "effective_from": "2026-01-01",
"citations": [{"chunk": chunk_id, "quote": "只算已支付的订单"}]},
"open_questions": [],
}
return json.dumps({
"entry_fields": [{"name": "store", "type": "string", "required": False, "default": "",
"description": "门店(留空是全部门店)"}],
"sql": sql or "SELECT COUNT(*) * 1.0 AS refund_rate FROM orders WHERE status = 'paid' "
"AND store = '{{ input.store }}'",
"metrics": metrics if metrics is not None else [metric],
"open_questions": list(questions or []),
}, ensure_ascii=False)
class FakeModel:
"""起草模型:ainvoke 返回带 .content 的对象;按顺序交回复,交完重复最后一份。"""
model_name = "fake-model"
def __init__(self, replies: list[str]) -> None:
self.replies = list(replies)
self.calls: list[list] = []
async def ainvoke(self, messages):
self.calls.append(list(messages))
from types import SimpleNamespace
return SimpleNamespace(content=self.replies.pop(0) if len(self.replies) > 1 else self.replies[0])
def fake_model(monkeypatch, *replies: str) -> FakeModel:
model = FakeModel(list(replies))
async def resolve(_session):
from types import SimpleNamespace
return model, model.model_name, SimpleNamespace(available=True, reason="")
monkeypatch.setattr(recipe_ai, "resolve_draft_model", resolve)
return model
@pytest.fixture
@@ -50,114 +90,230 @@ async def client():
yield c
@pytest.fixture
async def documents():
"""建文档和段落(ordinal 故意倒着插,确认读出来按 ordinal 排)。段落 id 带上文档 id,测试之间不撞。
测试结束删掉这几份文档、它们的段落和所有草稿。"""
@pytest.fixture(autouse=True)
async def fake_trial(monkeypatch):
"""试跑换成写一行 succeeded 的运行:不启动引擎、不查库,接口和 payload 的形状照真的一样。"""
made: list[str] = []
async def make(doc_id: str, *, title: str = "销售口径.md", collection: str = "default",
chunks=((2, "退款率 = 已支付后退款的订单数 / 已支付订单数"), (1, "退款率按门店拆"))) -> str:
async def start(*, draft_id, workflow_id, graph, values, started_by):
run_id = f"run-draft-{uuid.uuid4().hex[:10]}"
async with SessionLocal() as session:
session.add(Run(id=run_id, workflow_id=workflow_id, status="succeeded", graph=graph,
input=values, run_class="exploratory", origin_kind="caliber_trial",
origin={"kind": "caliber_trial", "draft_id": draft_id,
"workflow_id": workflow_id, "version": 1}))
await session.commit()
made.append(run_id)
return {"run_id": run_id, "status": "succeeded", "error": ""}
monkeypatch.setattr(api_ledger, "_run_trial", start)
yield made
async with SessionLocal() as session:
for run_id in made:
row = await session.get(Run, run_id)
if row is not None:
await session.delete(row)
await session.commit()
@pytest.fixture
async def documents():
"""建文档和段落(ordinal 故意倒着插,确认读出来按 ordinal 排)。测试结束删文档、段落、草稿和草稿建出的工作流。"""
made: list[str] = []
async def make(doc_id: str, *, title: str = "销售口径.md", collection: str = "default") -> str:
chunks = ((2, CHUNK_TWO), (1, CHUNK_ONE))
async with SessionLocal() as session:
session.add(Document(id=doc_id, collection=collection, 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))
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]
# attach 会把 workflow_id 换成接上的那一份;起草时建的那份仍在 payload 里,照样要清掉
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(workflow_ids))
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))
doc = await session.get(Document, doc_id)
if doc is not None:
await session.delete(doc)
for draft in (await session.execute(select(CaliberDraft))).scalars():
await session.delete(draft)
await session.commit()
def fake_extract(monkeypatch, *results: dict, seen: dict | None = None) -> None:
"""把 docdraft.extract 换成固定结果:每次调用按顺序交一份,交完了重复最后一份。"""
queue = list(results)
@pytest.fixture
async def datasource():
"""一个有表结构的数据源:SQL 只能照这里的表写。"""
source_id = f"ds-{uuid.uuid4().hex[:10]}"
async def extract(session, *, docs, chunks, guidance="", datasource=None, model=None):
if seen is not None:
seen.update(docs=docs, chunks=chunks, guidance=guidance, datasource=datasource)
return copy.deepcopy(queue.pop(0) if len(queue) > 1 else queue[0])
async def make(*, tables: bool = True) -> str:
cache = {"tables": {"orders": {"columns": [
{"name": "status", "type": "TEXT"}, {"name": "store", "type": "TEXT"},
{"name": "amount", "type": "NUMERIC"}, {"name": "paid_at", "type": "TEXT"}]}}, "total": 1} \
if tables else {}
async with SessionLocal() as session:
session.add(DataSource(id=source_id, name=f"shop_{uuid.uuid4().hex[:8]}", kind="sqlite",
description="销售库", schema_cache=cache))
await session.commit()
return source_id
monkeypatch.setattr(docdraft, "extract", extract)
yield make
async with SessionLocal() as session:
row = await session.get(DataSource, source_id)
if row is not None:
await session.delete(row)
await session.commit()
async def test_extract_reads_documents_in_order_and_stores_a_questions_open_draft(client, documents, monkeypatch):
doc = await documents("d-draft-1")
seen: dict = {}
fake_extract(monkeypatch, result(questions=["按哪个时区结算"]), seen=seen)
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
res = await client.post("/api/ledger/drafts/extract",
json={"documents": [doc], "guidance": "只看已支付的订单"})
assert res.status_code == 201, res.text
body = res.json()
assert set(body) == {"draft_id", "status"}
# 抽取在后台跑:建行那一刻回 drafting,结果用 GET 看
# ==========================================================================
# 主路径
# ==========================================================================
async def test_extract_produces_a_ready_draft_with_a_graph_and_a_trial(client, documents, datasource, monkeypatch):
doc = await documents("dd-1")
source_id = await datasource()
fake_model(monkeypatch, plan_reply(f"{doc}-2"))
body = await extract(client, doc, source_id)
assert body["status"] == "drafting"
# 交给模型的是按 ordinal 排好的段落,标题和 guidance 也传下去了
first, second = f"{doc}-1", f"{doc}-2"
assert seen["docs"] == [{"document_id": doc, "title": "销售口径.md", "chunk_ids": [first, second]}]
assert [seen["chunks"][c]["ordinal"] for c in (first, second)] == [1, 2]
assert seen["chunks"][first]["document_id"] == doc
assert seen["guidance"] == "只看已支付的订单" and seen["datasource"] is None
made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json()
assert made["status"] == "questions_open" and made["title"] == "销售口径.md"
assert made["workflow_id"] is None and made["workflow_name"] is None
assert made["model_id"] == "fake-model"
assert made["status"] == "ready"
assert made["title"] == "销售口径.md"
assert made["workflow_id"] and made["workflow_name"] == "销售口径.md"
assert made["metric_count"] == 1 and made["question_count"] == 0
assert [m["name"] for m in made["metrics"]] == ["已支付退款率"]
assert made["metrics"][0]["definition"]["citations"][0]["span"] == [0, 2]
assert made["open_questions"] == ["按哪个时区结算"]
assert made["dropped"] == [{"name": "第 2 条", "reason": "没有一条引用能在原文里逐字核对上"}]
assert set(made["alignment"]) == {"new", "duplicate", "conflict"}
assert made["metrics"][0]["expression"] == "cell(nodes.fetch, 0, 'refund_rate')"
assert made["metrics"][0]["definition"]["citations"][0]["span"] == [8, 16]
assert made["sql"].startswith("SELECT COUNT(*)") and "{{ input.store }}" in made["sql"]
assert [f["name"] for f in made["entry_fields"]] == ["store"]
assert made["trial"]["run_id"] and made["trial"]["status"] == "succeeded"
assert [d["document_id"] for d in made["documents"]] == [doc]
assert made["documents"][0]["chunk_ids"] == [f"{doc}-1", f"{doc}-2"]
assert made["alignment"]["new"] == ["已支付退款率"]
assert made["truncated"] is False
assert made["origin"] == {"documents": [doc], "guidance": "只看已支付的订单"}
# 草稿不写进工作流:库里没有从它建出的图
assert made["truncated"] is False and made["model_id"] == "fake-model"
assert made["datasource_id"] == source_id
# 工作流和 v1 已建:合法的草稿图,取数指向这个数据源
async with SessionLocal() as session:
row = await session.get(CaliberDraft, body["draft_id"])
assert row.workflow_id is None and row.payload["metrics"][0]["name"] == "已支付退款率"
workflow = await session.get(Workflow, row.workflow_id)
version = (await session.execute(select(WorkflowVersion).where(
WorkflowVersion.workflow_id == row.workflow_id))).scalars().one()
assert workflow.status == "draft" and workflow.tags == ["doc_draft"]
assert version.version == 1 and version.graph == workflow.graph
assert [n["id"] for n in workflow.graph["nodes"]] == ["start", "fetch", "card", "write", "out"]
assert validate_graph(GraphSpec.model_validate(workflow.graph)).ok
# 试跑只读接口:契约里的形状
trial = (await client.get(f"/api/ledger/drafts/{body['draft_id']}/trial")).json()
assert set(trial) == {"run_id", "status", "metrics", "error"}
assert trial["run_id"] == made["trial"]["run_id"] and trial["status"] == "succeeded"
async def test_extract_without_open_questions_is_path_pending(client, documents, monkeypatch):
doc = await documents("d-draft-2")
fake_extract(monkeypatch, result(metrics=[{**METRIC, "open_questions": []}]))
body = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()
assert body["status"] == "drafting"
async def test_open_questions_keep_the_draft_in_questions_open_but_still_run_it(
client, documents, datasource, monkeypatch):
doc = await documents("dd-2")
source_id = await datasource()
fake_model(monkeypatch, plan_reply(f"{doc}-2", questions=["退款算在哪一天"]))
body = await extract(client, doc, source_id)
made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json()
assert made["status"] == "path_pending"
assert made["open_questions"] == [] and made["question_count"] == 0
assert made["status"] == "questions_open"
assert made["open_questions"] == ["退款算在哪一天"]
assert made["workflow_id"] and made["sql"]
assert made["trial"]["status"] == "succeeded"
async def test_a_missing_document_is_refused_and_no_draft_is_created(client):
res = await client.post("/api/ledger/drafts/extract", json={"documents": ["d-nope"]})
async def test_a_missing_or_empty_datasource_is_refused_and_no_draft_is_created(client, documents, datasource):
doc = await documents("dd-3")
without = await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})
assert without.status_code == 422 and "数据源" in without.text
unknown = await client.post("/api/ledger/drafts/extract",
json={"documents": [doc], "datasource_id": "ds-nope"})
assert unknown.status_code == 422 and "数据源不存在" in unknown.text
empty_source = await datasource(tables=False)
empty = await client.post("/api/ledger/drafts/extract",
json={"documents": [doc], "datasource_id": empty_source})
assert empty.status_code == 422 and "表结构" in empty.text
assert (await client.get("/api/ledger/drafts")).json()["drafts"] == []
async def test_a_missing_document_is_refused_and_no_draft_is_created(client, datasource):
source_id = await datasource()
res = await client.post("/api/ledger/drafts/extract",
json={"documents": ["d-nope"], "datasource_id": source_id})
assert res.status_code == 422 and "d-nope" in res.text
listed = (await client.get("/api/ledger/drafts")).json()
assert listed["drafts"] == []
assert (await client.get("/api/ledger/drafts")).json()["drafts"] == []
async def test_patch_replaces_metrics_and_clears_resolved_questions(client, documents, monkeypatch):
doc = await documents("d-draft-3")
fake_extract(monkeypatch, result(questions=["按哪个时区结算"]))
draft_id = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()["draft_id"]
async def test_sql_outside_the_catalog_fails_the_draft_with_a_reason(client, documents, datasource, monkeypatch):
doc = await documents("dd-4")
source_id = await datasource()
fake_model(monkeypatch, plan_reply(f"{doc}-2", sql="SELECT * FROM secrets"))
fixed_metric = {**copy.deepcopy(METRIC), "open_questions": [], "name": "已支付退款率(按支付日)"}
body = await extract(client, doc, source_id)
made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json()
assert made["status"] == "failed" and made["workflow_id"] is None
assert "secrets" in made["error"] and "数据目录" in made["error"]
assert any("secrets" in d["reason"] for d in made["dropped"])
assert not made.get("sql")
assert (await client.get(f"/api/ledger/drafts/{body['draft_id']}/trial")).status_code == 404
async def test_a_metric_with_a_bad_expression_is_dropped_but_the_draft_still_goes_on(
client, documents, datasource, monkeypatch):
doc = await documents("dd-5")
source_id = await datasource()
reply = json.loads(plan_reply(f"{doc}-2"))
reply["metrics"].append({**reply["metrics"][0], "id": "m2", "name": "订单数", "expression": "SUM(amount)"})
fake_model(monkeypatch, json.dumps(reply, ensure_ascii=False))
body = await extract(client, doc, source_id)
made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json()
# 一条好、一条坏:坏的那条进 dropped / open_questions,草稿照样 ready 之外还有图
assert [m["id"] for m in made["metrics"]] == ["m1"]
assert any(d["name"] == "订单数" and "cell(nodes.fetch, 0" in d["reason"] for d in made["dropped"])
assert any("订单数" in q for q in made["open_questions"])
assert made["status"] == "questions_open" and made["workflow_id"]
# ==========================================================================
# 改、驳回、列表、试跑接口
# ==========================================================================
async def test_patch_replaces_metrics_and_clears_resolved_questions(client, documents, datasource, monkeypatch):
doc = await documents("dd-6")
source_id = await datasource()
fake_model(monkeypatch, plan_reply(f"{doc}-2", questions=["按哪个时区结算"]))
draft_id = (await extract(client, doc, source_id))["draft_id"]
fixed = {**copy.deepcopy(json.loads(plan_reply(f"{doc}-2"))["metrics"][0]), "name": "已支付退款率(按支付日)"}
res = await client.patch(f"/api/ledger/drafts/{draft_id}",
json={"title": "退款率口径", "metrics": [fixed_metric],
"resolved": ["按哪个时区结算", "退款算不算已支付当天的"]})
json={"title": "退款率口径", "metrics": [fixed],
"resolved": ["按哪个时区结算"]})
assert res.status_code == 200, res.text
made = res.json()
assert made["title"] == "退款率口径" and made["status"] == "path_pending"
assert made["title"] == "退款率口径" and made["status"] == "ready"
assert [m["name"] for m in made["metrics"]] == ["已支付退款率(按支付日)"]
assert made["open_questions"] == [] and made["question_count"] == 0
@@ -169,14 +325,15 @@ async def test_patch_replaces_metrics_and_clears_resolved_questions(client, docu
# 还有问题(只换指标、带着新问题)→ questions_open
res = await client.patch(f"/api/ledger/drafts/{draft_id}",
json={"metrics": [{**fixed_metric, "open_questions": ["按哪个门店口径"]}]})
json={"metrics": [{**fixed, "open_questions": ["按哪个门店口径"]}]})
assert res.json()["status"] == "questions_open" and res.json()["question_count"] == 1
async def test_dismiss_marks_rejected_and_writes_an_audit(client, documents, monkeypatch):
doc = await documents("d-draft-4")
fake_extract(monkeypatch, result())
draft_id = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()["draft_id"]
async def test_dismiss_marks_rejected_and_writes_an_audit(client, documents, datasource, monkeypatch):
doc = await documents("dd-7")
source_id = await datasource()
fake_model(monkeypatch, plan_reply(f"{doc}-2"))
draft_id = (await extract(client, doc, source_id))["draft_id"]
res = await client.post(f"/api/ledger/drafts/{draft_id}/dismiss", json={"note": "已经有口径了"})
assert res.status_code == 200 and res.json()["status"] == "rejected"
@@ -187,23 +344,23 @@ async def test_dismiss_marks_rejected_and_writes_an_audit(client, documents, mon
assert (await client.get(f"/api/ledger/drafts/{draft_id}")).json()["status"] == "rejected"
async def test_list_counts_orders_by_last_change_and_filters_by_status(client, documents, monkeypatch):
first = await documents("d-draft-5", title="一.md")
second = await documents("d-draft-6", title="二.md")
fake_extract(monkeypatch,
result(metrics=[METRIC, {**METRIC, "name": "退款金额", "open_questions": []}],
questions=["按哪个时区结算"]),
result(metrics=[{**METRIC, "open_questions": []}]))
one = (await client.post("/api/ledger/drafts/extract", json={"documents": [first]})).json()["draft_id"]
two = (await client.post("/api/ledger/drafts/extract", json={"documents": [second]})).json()["draft_id"]
async def test_list_counts_orders_by_last_change_and_filters_by_status(client, documents, datasource, monkeypatch):
first = await documents("dd-8", title="一.md")
second = await documents("dd-9", title="二.md")
source_id = await datasource()
fake_model(monkeypatch,
plan_reply(f"{first}-2", questions=["按哪个时区结算"]),
plan_reply(f"{second}-2"))
one = (await extract(client, first, source_id))["draft_id"]
two = (await extract(client, second, source_id))["draft_id"]
listed = (await client.get("/api/ledger/drafts")).json()["drafts"]
assert [d["id"] for d in listed] == [two, one]
latest, earlier = listed
assert (latest["title"], latest["status"], latest["metric_count"], latest["question_count"]) == \
("二.md", "path_pending", 1, 0)
assert (earlier["status"], earlier["metric_count"], earlier["question_count"]) == ("questions_open", 2, 2)
assert earlier["workflow_id"] is None and earlier["created_at"] and earlier["error"] is None
("二.md", "ready", 1, 0)
assert (earlier["status"], earlier["metric_count"], earlier["question_count"]) == ("questions_open", 1, 1)
assert earlier["workflow_id"] and earlier["created_at"] and earlier["error"] is None
only = (await client.get("/api/ledger/drafts", params={"status": "questions_open"})).json()["drafts"]
assert [d["id"] for d in only] == [one]
@@ -211,24 +368,57 @@ async def test_list_counts_orders_by_last_change_and_filters_by_status(client, d
assert (await client.get("/api/ledger/drafts/d-nope")).status_code == 404
async def test_a_model_that_is_unavailable_leaves_the_draft_with_an_error(client, documents, monkeypatch):
doc = await documents("d-draft-7")
async def test_trial_endpoint_returns_metric_values_from_the_run(client, documents, datasource, monkeypatch):
doc = await documents("dd-10")
source_id = await datasource()
fake_model(monkeypatch, plan_reply(f"{doc}-2"))
draft_id = (await extract(client, doc, source_id))["draft_id"]
async def unavailable(session, **kwargs):
raise docdraft.DraftUnavailable("还没有接入可用的起草模型")
async def metrics(_run_id):
return [{"id": "m1", "name": "已支付退款率", "rendered": "3.2%", "value": 0.032}]
monkeypatch.setattr(docdraft, "extract", unavailable)
body = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()
monkeypatch.setattr(api_ledger, "_trial_metrics", metrics)
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",
"metrics": [{"id": "m1", "name": "已支付退款率", "rendered": "3.2%", "value": 0.032}],
"error": ""}
# 没有试跑的老草稿
async with SessionLocal() as session:
session.add(CaliberDraft(id=f"draft-old-{uuid.uuid4().hex[:8]}", title="老草稿", status="path_pending",
payload={"metrics": []}))
await session.commit()
old = (await session.execute(select(CaliberDraft.id).where(
CaliberDraft.status == "path_pending"))).scalars().first()
assert (await client.get(f"/api/ledger/drafts/{old}/trial")).status_code == 404
async def test_a_model_that_is_unavailable_leaves_the_draft_with_an_error(client, documents, datasource,
monkeypatch):
doc = await documents("dd-11")
source_id = await datasource()
async def unavailable(_session):
from types import SimpleNamespace
return None, "", SimpleNamespace(available=False, reason="还没有接入可用的起草模型")
monkeypatch.setattr(recipe_ai, "resolve_draft_model", unavailable)
body = await extract(client, doc, source_id)
made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json()
assert made["status"] == "failed" and made["error"] == "还没有接入可用的起草模型"
assert made["metric_count"] == 0 and not made.get("metrics")
async def test_attach_hands_the_draft_to_docattach_and_records_the_workflow(client, documents, monkeypatch):
"""attach 只按约定调 app.ledger.docattach.attach(另一路实现):这里换成一个假的模块,看接线和写回。"""
doc = await documents("d-draft-8")
fake_extract(monkeypatch, result(metrics=[{**METRIC, "open_questions": []}]))
draft_id = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()["draft_id"]
async def test_attach_hands_the_draft_to_docattach_and_records_the_workflow(client, documents, datasource,
monkeypatch):
"""attach 只按约定调 app.ledger.docattach.attach(辅助入口):这里换成一个假的模块,看接线和写回。"""
doc = await documents("dd-12")
source_id = await datasource()
fake_model(monkeypatch, plan_reply(f"{doc}-2"))
draft_id = (await extract(client, doc, source_id))["draft_id"]
seen: dict = {}
@@ -257,3 +447,63 @@ async def test_attach_hands_the_draft_to_docattach_and_records_the_workflow(clie
if workflow is not None:
await session.delete(workflow)
await session.commit()
async def test_a_real_trial_run_feeds_the_trial_endpoint(client, documents, tmp_path, monkeypatch):
"""真引擎跑一次草稿图:数从取数节点进口径卡,GET /trial 交回指标值(不 mock 试跑)。"""
from app.engine.runner import run_manager
from tests import ledger_samples as S
await run_manager.setup()
run_id = None
try:
name = await S.fresh_source(tmp_path / "shop.db")
async with SessionLocal() as session:
row = (await session.execute(select(DataSource).where(DataSource.name == name))).scalar_one()
row.schema_cache = {"tables": {"orders": {"columns": [
{"name": "status", "type": "TEXT"}, {"name": "region", "type": "TEXT"},
{"name": "amount", "type": "REAL"}, {"name": "paid_at", "type": "TEXT"}]}}, "total": 1}
await session.commit()
source_id = row.id
doc = await documents("dd-real")
reply = json.loads(plan_reply(f"{doc}-2"))
reply["entry_fields"] = [{"name": "region", "type": "string", "required": False,
"default": "east", "description": "区域"}]
reply["sql"] = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' "
"AND region = '{{ input.region }}'")
reply["metrics"][0].update({"expression": "cell(nodes.fetch, 0, 'gmv')", "name": "已支付销售额",
"unit": "元", "decimals": 2})
fake_model(monkeypatch, json.dumps(reply, ensure_ascii=False))
# 报告节点也要一个模型:用品自带的 mock 模型,正文引用卡上的指标,核对规则照过
S.script(monkeypatch, "已支付销售额 [[m:m1]]。")
monkeypatch.setattr(api_ledger, "_run_trial", REAL_RUN_TRIAL)
draft_id = (await extract(client, doc, source_id))["draft_id"]
made = (await client.get(f"/api/ledger/drafts/{draft_id}")).json()
assert made["status"] == "ready" and made["trial"]["status"] == "succeeded", made.get("error")
run_id = made["trial"]["run_id"]
trial = (await client.get(f"/api/ledger/drafts/{draft_id}/trial")).json()
assert trial["status"] == "succeeded" and trial["error"] == ""
assert [m["id"] for m in trial["metrics"]] == ["m1"]
assert trial["metrics"][0]["name"] == "已支付销售额"
assert float(trial["metrics"][0]["value"]) == 156.5
async with SessionLocal() as session:
run = await session.get(Run, run_id)
assert run.origin_kind == "caliber_trial" and run.run_class == "exploratory"
assert not [n for n in (run.graph or {}).get("nodes") or [] if n.get("type") == "report"], \
"试跑只跑取数与口径卡,不该触发报告撰写"
assert run.origin["kind"] == "caliber_trial" and run.origin["draft_id"] == draft_id
assert run.origin["workflow_id"] == made["workflow_id"] and run.origin["version"] == 1
finally:
await run_manager.shutdown()
async with SessionLocal() as session:
if run_id:
row = await session.get(Run, run_id)
if row is not None:
await session.delete(row)
source = (await session.execute(select(DataSource).where(
DataSource.name == S.CURRENT["source"]))).scalars().first()
if source is not None:
await session.delete(source)
await session.commit()
+200
View File
@@ -0,0 +1,200 @@
"""口径一次起草的纯逻辑(app/ledger/draftplan.py)。
- SQL 只收单条只读 SELECT:多语句、注释后藏的第二条、写操作、目录外的表一律拒;
- 指标表达式必须是 cell(nodes.fetch, 0, '列名');引用核不上的整条丢弃;
- build_graph 两次调用逐字一致,且能过 GraphSpec / validate_graph;
- plan 注入假模型(不发真实请求),材料里有表目录和原文。
"""
from __future__ import annotations
import json
from types import SimpleNamespace
import pytest
from app.engine.schema import GraphSpec, validate_graph
from app.ledger import draftplan
CHUNK = "销售额按已支付订单的支付时间归期统计,退款订单不计入销售额。"
CHUNKS = {"c1": {"ordinal": 1, "content": CHUNK, "document_id": "d1"}}
TABLES = {"orders", "customers"}
METRIC = {
"id": "m1",
"name": "销售额",
"synonyms": ["gmv"],
"unit": "元",
"decimals": 2,
"expression": "cell(nodes.fetch, 0, 'gmv')",
"definition": {"text": "已支付订单的销售额", "scope": "全部", "exclusions": [], "owner": "运营",
"effective_from": "2026-01-01",
"citations": [{"chunk": "c1", "quote": "销售额按已支付订单的支付时间归期统计"}]},
"open_questions": [],
}
def raw(**extra):
body = {
"entry_fields": [{"name": "start", "type": "string", "required": True, "default": "2026-09-01",
"description": "开始日期"}],
"sql": "SELECT SUM(amount) AS gmv FROM orders WHERE paid_at >= '{{ input.start }}'",
"metrics": [dict(METRIC)],
"open_questions": [],
}
body.update(extra)
return body
def sql_problem(sql: str) -> str | None:
plan, problems = draftplan.normalize_plan(raw(sql=sql), CHUNKS, allowed_tables=TABLES)
assert plan["sql"] == ""
reasons = [p["reason"] for p in problems if p["name"] == "sql"]
assert reasons, problems
return reasons[0]
# ==========================================================================
# normalize_plan:SQL 的硬规则
# ==========================================================================
def test_a_read_only_select_over_the_catalog_is_kept():
plan, problems = draftplan.normalize_plan(raw(), CHUNKS, allowed_tables=TABLES)
assert plan["sql"].endswith("'{{ input.start }}'")
assert [m["id"] for m in plan["metrics"]] == ["m1"]
assert plan["entry_fields"][0]["name"] == "start"
assert not [p for p in problems if p["name"] == "sql"]
def test_multiple_statements_and_a_hidden_second_statement_are_refused():
assert "只能是一条语句" in sql_problem(
"SELECT SUM(amount) AS gmv FROM orders; DROP TABLE orders")
# 注释后藏的第二条也解析成第二条语句
assert "只能是一条语句" in sql_problem(
"SELECT SUM(amount) AS gmv FROM orders; -- 收尾\nDELETE FROM orders")
def test_writes_and_ddl_are_refused():
assert "只读 SELECT" in sql_problem("DELETE FROM orders")
assert "只读 SELECT" in sql_problem("UPDATE orders SET amount = 0")
assert "只读 SELECT" in sql_problem("DROP TABLE orders")
def test_tables_outside_the_catalog_are_refused():
reason = sql_problem("SELECT * FROM secrets")
assert "secrets" in reason and "数据目录" in reason
# CTE 名字不是表;真正的表没在目录里照样拒
reason = sql_problem("WITH x AS (SELECT * FROM secrets) SELECT * FROM x")
assert "secrets" in reason
def test_a_cte_over_a_catalog_table_is_allowed():
plan, problems = draftplan.normalize_plan(
raw(sql="WITH paid AS (SELECT amount FROM orders) SELECT SUM(amount) AS gmv FROM paid"),
CHUNKS, allowed_tables=TABLES)
assert plan["sql"].startswith("WITH paid")
assert not [p for p in problems if p["name"] == "sql"]
def test_an_undeclared_template_field_invalidates_the_sql():
plan, problems = draftplan.normalize_plan(
raw(sql="SELECT SUM(amount) AS gmv FROM orders WHERE paid_at >= '{{ input.nope }}'"),
CHUNKS, allowed_tables=TABLES)
assert plan["sql"] == ""
assert any("nope" in p["reason"] for p in problems)
# ==========================================================================
# normalize_plan:指标
# ==========================================================================
def test_a_bad_expression_drops_only_that_metric():
plan, problems = draftplan.normalize_plan(
raw(metrics=[{**METRIC, "expression": "SUM(amount)"}, {**dict(METRIC), "id": "m2"}]),
CHUNKS, allowed_tables=TABLES)
assert [m["id"] for m in plan["metrics"]] == ["m2"]
assert any(p["name"] == "销售额" and "cell(nodes.fetch, 0" in p["reason"] for p in problems)
def test_a_metric_whose_quotes_do_not_match_the_source_is_dropped():
plan, problems = draftplan.normalize_plan(
raw(metrics=[{**METRIC, "definition": {**METRIC["definition"],
"citations": [{"chunk": "c1", "quote": "原文里没有这句"}]}}]),
CHUNKS, allowed_tables=TABLES)
assert plan["metrics"] == []
assert any(p["name"] == "销售额" and "引用" in p["reason"] for p in problems)
assert any(p["name"] == "metrics" for p in problems)
def test_metric_ids_are_unique_and_entry_fields_are_normalized():
plan, _problems = draftplan.normalize_plan(
raw(entry_fields=[{"name": "start", "type": "date", "required": 1, "default": "2026-09-01"}],
metrics=[dict(METRIC), {**dict(METRIC), "name": "订单数"}]),
CHUNKS, allowed_tables=TABLES)
assert [m["id"] for m in plan["metrics"]] == ["m1", "m2"]
assert plan["entry_fields"][0]["type"] == "string"
assert plan["entry_fields"][0]["required"] is True
# ==========================================================================
# build_graph
# ==========================================================================
def test_build_graph_is_deterministic_and_passes_validation():
plan, _ = draftplan.normalize_plan(raw(), CHUNKS, allowed_tables=TABLES)
plan["datasource"] = "shop"
first = draftplan.build_graph(plan, name="销售额口径", question="上周销售额")
second = draftplan.build_graph(plan, name="销售额口径", question="上周销售额")
assert first == second
assert [node["id"] for node in first["nodes"]] == ["start", "fetch", "card", "write", "out"]
fetch = next(node for node in first["nodes"] if node["id"] == "fetch")
assert fetch["data"]["config"] == {"tool": "db_query__shop", "args": {"sql": plan["sql"]}}
card = next(node for node in first["nodes"] if node["id"] == "card")
assert card["data"]["config"]["metrics"][0]["id"] == "m1"
contract = next(node for node in first["nodes"] if node["id"] == "out")["data"]["config"]["contract"]
assert contract["metrics_from"] == "card" and contract["required"] == ["m1"]
report = next(node for node in first["nodes"] if node["id"] == "write")["data"]["config"]
assert report["numbers"] == "strict" and report["metrics_from"] == ["card"]
result = validate_graph(GraphSpec.model_validate(first))
assert result.ok, [issue.message for issue in result.issues if issue.level == "error"]
# ==========================================================================
# plan:注入假模型
# ==========================================================================
class FakeModel:
model_name = "fake-plan-model"
def __init__(self, text: str) -> None:
self.text = text
self.messages: list = []
async def ainvoke(self, messages):
self.messages = messages
return SimpleNamespace(content=self.text)
async def test_plan_hands_the_model_the_table_catalog_and_the_source_text():
model = FakeModel(json.dumps({**raw(), "model_id": "ignored"}, ensure_ascii=False))
result = await draftplan.plan(
None, docs=[{"document_id": "d1", "title": "销售口径.md"}], chunks=CHUNKS,
guidance="只看已支付", datasource={"name": "shop", "type": "sqlite"},
tables_text="表 orders(订单)\n amount 金额", model=model)
assert result["model_id"] == "fake-plan-model"
assert result["sql"].startswith("SELECT SUM(amount)")
assert result["metrics"][0]["name"] == "销售额"
human = model.messages[-1].content
assert "表 orders" in human and "amount 金额" in human
assert CHUNK in human and "只看已支付" in human
async def test_plan_refuses_when_no_draft_model_is_available(monkeypatch):
from app.data import recipe_ai
from app.ledger import docdraft
async def resolve(_session):
return None, "", SimpleNamespace(available=False, reason="还没有接入可用的起草模型")
monkeypatch.setattr(recipe_ai, "resolve_draft_model", resolve)
with pytest.raises(docdraft.DraftUnavailable, match="起草模型"):
await draftplan.plan(None, docs=[], chunks={})